Package: git-man
Version: 1:2.47.2-0.1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff:<stdin>:902: warning [page 10, line 29]: cannot break line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.17-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
-- no debconf information
Input file is git-filter-branch.1
Output from "mandoc -T lint git-filter-branch.1": (shortened list)
1 input text line longer than 80 bytes: (if the parent strin...
1 input text line longer than 80 bytes: A \fImap\fR function...
1 input text line longer than 80 bytes: A minor issue, but u...
1 input text line longer than 80 bytes: Always verify that t...
1 input text line longer than 80 bytes: Annotated tags can b...
1 input text line longer than 80 bytes: Any commit messages ...
1 input text line longer than 80 bytes: As a special extensi...
1 input text line longer than 80 bytes: By using \fBgit-rev-...
1 input text line longer than 80 bytes: Coming up with the c...
1 input text line longer than 80 bytes: Commit messages (eve...
1 input text line longer than 80 bytes: Even if you don\(cqt...
1 input text line longer than 80 bytes: Filenames with space...
1 input text line longer than 80 bytes: Further, several add...
1 input text line longer than 80 bytes: However, if the file...
3 input text line longer than 80 bytes: If \-\-prune\-empty ...
1 input text line longer than 80 bytes: If any evaluation of...
1 input text line longer than 80 bytes: If the user provides...
1 input text line longer than 80 bytes: If you need to add \...
1 input text line longer than 80 bytes: If you really don\(c...
1 input text line longer than 80 bytes: If you try and cheat...
1 input text line longer than 80 bytes: In editing files, gi...
1 input text line longer than 80 bytes: It\(cqs far too easy...
1 input text line longer than 80 bytes: Lets you rewrite Git...
1 input text line longer than 80 bytes: Nearly proper rewrit...
1 input text line longer than 80 bytes: Non\-ascii filenames...
1 input text line longer than 80 bytes: Note that since this...
1 input text line longer than 80 bytes: On success, the exit...
1 input text line longer than 80 bytes: Only look at the his...
1 input text line longer than 80 bytes: Running git\-filter\...
1 input text line longer than 80 bytes: Side note: Unfortuna...
1 input text line longer than 80 bytes: Similarly, when movi...
1 input text line longer than 80 bytes: Some filters will ge...
1 input text line longer than 80 bytes: Someone can do a his...
1 input text line longer than 80 bytes: Someone can have a s...
1 input text line longer than 80 bytes: Suppose you want to ...
1 input text line longer than 80 bytes: The \fB\-\-env\-filt...
1 input text line longer than 80 bytes: The \m[blue]\fBgit f...
1 input text line longer than 80 bytes: The command will onl...
1 input text line longer than 80 bytes: The filters are appl...
1 input text line longer than 80 bytes: The original tags ar...
1 input text line longer than 80 bytes: The performance of g...
1 input text line longer than 80 bytes: The shift magic firs...
1 input text line longer than 80 bytes: The user\-provided s...
1 input text line longer than 80 bytes: Then there are two w...
1 input text line longer than 80 bytes: There are no facilit...
1 input text line longer than 80 bytes: This filter may be u...
1 input text line longer than 80 bytes: This is not a real f...
6 input text line longer than 80 bytes: This is the filter f...
1 input text line longer than 80 bytes: This option will cau...
1 input text line longer than 80 bytes: Thus you can, e\&.g\...
1 input text line longer than 80 bytes: To restrict rewritin...
1 input text line longer than 80 bytes: To rewrite the repos...
1 input text line longer than 80 bytes: To set a commit (whi...
1 input text line longer than 80 bytes: To top it all off, e...
2 input text line longer than 80 bytes: Use this option to s...
1 input text line longer than 80 bytes: Using \fB\-\-index\-...
1 input text line longer than 80 bytes: You can rewrite the ...
1 input text line longer than 80 bytes: You really removed a...
1 input text line longer than 80 bytes: argument could no lo...
1 input text line longer than 80 bytes: command, with argume...
1 input text line longer than 80 bytes: commits, but each co...
1 input text line longer than 80 bytes: convenience function...
1 input text line longer than 80 bytes: even if you succeed ...
3 input text line longer than 80 bytes: git\-filter\-branch ...
1 input text line longer than 80 bytes: if you don\(cqt wish...
1 input text line longer than 80 bytes: refuses to start wit...
1 input text line longer than 80 bytes: the fact that \-\-ta...
1 input text line longer than 80 bytes: the fact that little...
1 input text line longer than 80 bytes: you run into problem...
1 skipping paragraph macro: PP after SH
9 skipping paragraph macro: sp after SH
2 skipping paragraph macro: sp after SS
-.-.
Output from "test-nroff -mandoc -t -ww -z git-filter-branch.1": (shortened list)
1 cannot break line
-.-.
Lines containing '\c':
447:\h'-04'\(bu\h'+03'\c
460:\h'-04'\(bu\h'+03'\c
475:\h'-04'\(bu\h'+03'\c
490:\h'-04'\(bu\h'+03'\c
502:\h'-04'\(bu\h'+03'\c
514:\h'-04'\(bu\h'+03'\c
533:\h'-04'\(bu\h'+03'\c
552:\h'-04'\(bu\h'+03'\c
562:\h'-04'\(bu\h'+03'\c
573:\h'-04'\(bu\h'+03'\c
585:\h'-04'\(bu\h'+03'\c
596:\h'-04'\(bu\h'+03'\c
607:\h'-04'\(bu\h'+03'\c
618:\h'-04'\(bu\h'+03'\c
628:\h'-04'\(bu\h'+03'\c
647:\h'-04'\(bu\h'+03'\c
658:\h'-04'\(bu\h'+03'\c
669:\h'-04'\(bu\h'+03'\c
681:\h'-04'\(bu\h'+03'\c
692:\h'-04'\(bu\h'+03'\c
702:\h'-04'\(bu\h'+03'\c
714:\h'-04'\(bu\h'+03'\c
725:\h'-04'\(bu\h'+03'\c
736:\h'-04'\(bu\h'+03'\c
748:\h'-04'\(bu\h'+03'\c
758:\h'-04'\(bu\h'+03'\c
769:\h'-04'\(bu\h'+03'\c
781:\h'-04'\(bu\h'+03'\c
792:\h'-04'\(bu\h'+03'\c
803:\h'-04'\(bu\h'+03'\c
814:\h'-04'\(bu\h'+03'\c
825:\h'-04'\(bu\h'+03'\c
836:\h'-04'\(bu\h'+03'\c
847:\h'-04'\(bu\h'+03'\c
858:\h'-04'\(bu\h'+03'\c
871:\h'-04'\(bu\h'+03'\c
882:\h'-04'\(bu\h'+03'\c
Use a macro for repeated use of the same code.
-.-
Show if docman-to-man created this.
Who is actually creating this man page? Debian or upstream?
Is the generating software out of date?
3:.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4:.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URL (web address)
902 \%https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
-.-
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
[List of affected lines removed.]
-.-
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of
a) an option in UTF-8 text
b) web addresses (URL).
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
897:\%https://github.com/newren/git-filter-repo/
902:\%https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
-.-.
No need for '\&' to be in front of a period (.),
if there is a character in front of it.
Remove with "sed -e 's/\\&\././g'".
[List with affected lines removed.]
Lines longer than about(?) 1023 forces a mail program to use quoted-printable
encoding which is bad. Translater program is unusable.
Line 877, length 1036
Coming up with the correct shell snippet to do the filtering you want is sometimes difficult unless you\(cqre just doing a trivial modification such as deleting a couple files\&. Unfortunately, people often learn if the snippet is right or wrong by trying it out, but the rightness or wrongness can vary depending on special circumstances (spaces in filenames, non\-ascii filenames, funny author names or emails, invalid timezones, presence of grafts or replace objects, etc\&.), meaning they may have to wait a long time, hit an error, then restart\&. The performance of git\-filter\-branch is so bad that this cycle is painful, reducing the time available to carefully re\-check (to say nothing about what it does to the patience of the person doing the rewrite even if they do technically have more time available)\&. This problem is extra compounded because errors from broken filters may not be shown for a long time and/or get lost in a sea of output\&. Even worse, broken filters often just result in silent incorrect rewrites\&.
-.-.
One space only after a possible end of sentence
(after a punctuation, that
can end a sentence).
[List of affected lines removed.]
-.-
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
git-filter-branch.1:10:.TH "GIT\-FILTER\-BRANCH" "1" "01/19/2025" "Git 2\&.47\&.2" "Git Manual"
git-filter-branch.1:30:.SH "NAME"
git-filter-branch.1:32:.SH "SYNOPSIS"
git-filter-branch.1:44:.SH "WARNING"
git-filter-branch.1:47:.SH "DESCRIPTION"
git-filter-branch.1:60:.SS "Filters"
git-filter-branch.1:67:.SH "OPTIONS"
git-filter-branch.1:195:.SH "EXAMPLES"
git-filter-branch.1:527:.SH "PERFORMANCE"
git-filter-branch.1:641:.SH "SAFETY"
git-filter-branch.1:890:.SH "GIT"
git-filter-branch.1:893:.SH "NOTES"
-.-.
Use ".na" (no adjustment) instead of ".ad l" (and ".ad" to begin the
same adjustment again as before).
26:.ad l
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
30:.SH "NAME"
32:.SH "SYNOPSIS"
44:.SH "WARNING"
47:.SH "DESCRIPTION"
60:.SS "Filters"
67:.SH "OPTIONS"
189:.SS "Remap to ancestor"
192:.SH "EXIT STATUS"
195:.SH "EXAMPLES"
441:.SH "CHECKLIST FOR SHRINKING A REPOSITORY"
527:.SH "PERFORMANCE"
641:.SH "SAFETY"
890:.SH "GIT"
893:.SH "NOTES"
-.-.
Remove excessive "\&" when it has no functional purpose.
46:\fIgit filter\-branch\fR has a plethora of pitfalls that can produce non\-obvious manglings of the intended history rewrite (and can leave you with little time to investigate such problems since it has such abysmal performance)\&. These safety and performance issues cannot be backward compatibly fixed and as such, its use is not recommended\&. Please use an alternative history filtering tool such as \m[blue]\fBgit filter\-repo\fR\m[]\&\s-2\u[1]\d\s+2\&. If you still need to use \fIgit filter\-branch\fR, please carefully read the section called \(lqSAFETY\(rq (and the section called \(lqPERFORMANCE\(rq) to learn about the land mines of filter\-branch, and then vigilantly avoid as many of the hazards listed there as reasonably possible\&.
640:The \m[blue]\fBgit filter\-repo\fR\m[]\&\s-2\u[1]\d\s+2 tool is an alternative to git\-filter\-branch which does not suffer from these performance problems or the safety problems (mentioned below)\&. For those with existing tooling which relies upon git\-filter\-branch, \fIgit filter\-repo\fR also provides \m[blue]\fBfilter\-lamely\fR\m[]\&\s-2\u[2]\d\s+2, a drop\-in git\-filter\-branch replacement (with a few caveats)\&. While filter\-lamely suffers from all the same safety issues as git\-filter\-branch, it at least ameliorates the performance issues a little\&.
-.-.
Use "\-" instead of "-" in web addresses.
16:.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
897:\%https://github.com/newren/git-filter-repo/
902:\%https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
-.-.
Put a (long) web address on a new line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.
897:\%https://github.com/newren/git-filter-repo/
902:\%https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
-.-.
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
troff:<stdin>:902: warning [page 10, line 29]: cannot break line
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- git-filter-branch.1 2025-03-13 02:10:27.604859557 +0000
+++ git-filter-branch.1.new 2025-03-13 18:02:25.935434652 +0000
@@ -894,10 +894,10 @@ Part of the \fBgit\fR(1) suite
.IP " 1." 4
git filter-repo
.RS 4
-\%https://github.com/newren/git-filter-repo/
+\%https://github.com/newren/git\-filter\-repo/
.RE
.IP " 2." 4
filter-lamely
.RS 4
-\%https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
+https://github.com/newren/git\-filter\-repo/\:blob/\:master/\:contrib/\:filter\-repo\-demos/\:filter\-lamely
.RE
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
