Subject: Re: [PATCH] doc: manpage: remove maximum title length

From: Felipe Contreras <[email-masked]>
Date: Wed, 03 May 2023 11:09:46 -0600

Jeff King wrote:
> On Tue, May 02, 2023 at 11:29:26PM -0600, Felipe Contreras wrote:
> 
> > 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.
> 
> Makes sense.
> 
> Since the manpage header shows the name twice, along with "Git Manual",
> the practical limit for an 80-column terminal is somewhere around 35
> characters. If it's not hard to do, it might be worth setting the value
> there,

It's not hard to do, but that would create a discrepancy with asciidoctor
manpage backend, which doesn't do that.

> I could also see an argument that the truncation is worse than any
> wrapping or other ugliness that the user might see on a smaller
> terminal, which implies that "no limit" as you have here is the best
> option.

I think it's best to remove the limit so there are no surprises and the output
is consistent among tools.

> > For example:
> > 
> > --- a/git-credential-cache--daemon.1
> > +++ b/git-credential-cache--daemon.1
> > @@ -1,4 +1,4 @@
> > -GIT-CREDENTIAL-CAC(1)             Git Manual             GIT-CREDENTIAL-CAC(1)
> > +GIT-CREDENTIAL-CACHE--DAEMON(1)   Git Manual   GIT-CREDENTIAL-CACHE--DAEMON(1)
> > 
> >  NAME
> >         git-credential-cache--daemon - Temporarily store user credentials in
> > @@ -24,4 +24,4 @@ DESCRIPTION
> >  GIT
> >         Part of the git(1) suite
> > 
> > -Git omitted                       2023-05-02             GIT-CREDENTIAL-CAC(1)
> > +Git omitted                       2023-05-02   GIT-CREDENTIAL-CACHE--DAEMON(1)
> 
> Your patch can't be applied by "git am" because of this diff in the
> commit message (it thinks the commit message stops at the first diff,
> even if it is before a "---" marker). The usual practice is to indent
> the included diff.

All right, I'll send an update.

-- 
Felipe Contreras