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

From: Jeff King <peff@peff.net>
Date: May 3, 2023, 16:43 UTC
Message-ID: <20230503164354.GC1789686@coredump.intra.peff.net>
In-Reply-To: <20230503052926.217219-1-felipe.contreras@gmail.com>

On Tue, May 02, 2023 at 11:29:26PM -0600, Felipe Contreras wrote:

Show 6 quoted lines

> 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, but I agree that we're unlikely to exceed that anyway, so it's probably not a big deal either way.

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.

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

-Peff