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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 3, 2023, 17:09 UTC
Message-ID: <6452955ade0c9_1df7294b9@chronos.notmuch>
In-Reply-To: <20230503164354.GC1789686@coredump.intra.peff.net>

Jeff King wrote:

Show 15 quoted lines

> 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.

Show 21 quoted lines

> > 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