The titles of manual pages used to be chomped at an unreasonably
short limit, which has been removed.
* fc/doc-man-lift-title-length-limit:
doc: manpage: remove maximum title length
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.
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)
Moreover, asciidoctor manpage backend doesn't limit the title length, so
we probably want to do the same for docbook backends for consistency.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The code to render callouts for manpages comes from 17 years ago:
776e994af5 (Properly render asciidoc "callouts" in git man pages.,
2006-04-28), and it was needed back then, but DocBook Stylesheets added
support for that in 2008 [1], since 1.74.0 it hasn't been necessary.
What's worse: the format of the upstream callouts is much nicer than our
hacked version.
Compare this:
$ git diff (1)
$ git diff --cached (2)
$ git diff HEAD (3)
1. Changes in the working tree not yet staged for the next
commit.
2. Changes between the index and your last commit; what you
would be committing if you run git commit without -a
option.
3. Changes in the working tree since your last commit; what
you would be committing if you run git commit -a
To this:
$ git diff (1)
$ git diff --cached (2)
$ git diff HEAD (3)
1. Changes in the working tree not yet staged for the next commit.
2. Changes between the index and your last commit; what you would
be committing if you run git commit without -a option.
3. Changes in the working tree since your last commit; what you
would be committing if you run git commit -a
Let's drop our unnecessary inferior custom format and use the official
one.
[1] https://sourceforge.net/p/docbook/code/7842/
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
After an earlier commit, we only include manpage-base.xsl from a single
file, manpage-normal.xsl. Fold the former into the latter.
We only ever needed the "base, normal and non-normal" construct to
support a single non-normal case, namely to work around issues with
docbook-xsl 1.72 handling backslashes and dots. If we ever need
something like this again, we can re-introduce manpage-base.xsl and
friends. Whatever issue we'd be trying to work around, it probably
wouldn't involve dots and backslashes like this, anyway.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Drop the DOCBOOK_XSL_172 config knob, which was needed with docbook-xsl
1.72 (but neither 1.71 nor 1.73). Version 1.73.0 is more than twelve
years old.
Together with the last few commits, we are now at a point where we don't
have any Makefile knobs to cater to old/broken versions of docbook-xsl.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The "spurious .sp" code should be independent of docbook-xsl
versions.
Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Parametrize the backslash and dot characters that are used to
generate roff control sequences in manpage-base.xsl.
Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Each of manpage-base.xsl and manpage-normal.xsl gets a copy of
the contents of callouts.xsl and the original is removed. The
Makefile is adjusted to refer to manpage-normal.xsl instead of
callouts.xsl. manpage-base.xsl will be later made into a common
base for -normal and -1.72.
Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
