Bug#1072837: List::Compare.3pm: some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sat Jun 8 18:26:35 BST 2024
Package: liblist-compare-perl
Version: 0.55-2
Severity: minor
Tags: patch
Dear Maintainer,
* What led up to the situation?
Checking for defects with
[test-]groff -mandoc -t -K utf8 -ww -b -z <man page>
[test-groff is a script in the repository for "groff"]
* What was the outcome of this action?
troff: backtrace: file '<stdin>':1516
troff:<stdin>:1516: warning: [page 17, 8.5i]: cannot break line
* What outcome did you expect instead?
No output (warnings).
-.-
The concerned man page was autogenerated.
Remarks and a patch are in the attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.7.12-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)
Versions of packages liblist-compare-perl depends on:
ii perl 5.38.2-5
liblist-compare-perl recommends no packages.
liblist-compare-perl suggests no packages.
-- no debconf information
-------------- next part --------------
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any generator should check its products with the above mentioned
'groff' and additionally with 'nroff ...'.
This is just a simple quality control measure.
The generator may have to be corrected to get a better man page,
the source file may, and any additional file may.
-.-
The difference between the formatted outputs can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -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 of "diff -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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint List::Compare.3pm": (possibly shortened list)
mandoc: List::Compare.3pm:1005:99: STYLE: input text line longer than 80 bytes: unsorted option (\f(...
mandoc: List::Compare.3pm:1006:99: STYLE: input text line longer than 80 bytes: (\f(CW\*(Aq\-a\*(Aq\...
mandoc: List::Compare.3pm:1041:108: STYLE: input text line longer than 80 bytes: optionally takes suc...
mandoc: List::Compare.3pm:1042:93: STYLE: input text line longer than 80 bytes: are skipped, \f(CW at a...
mandoc: List::Compare.3pm:1137:107: STYLE: input text line longer than 80 bytes: more lists, you can ...
mandoc: List::Compare.3pm:1155:109: STYLE: input text line longer than 80 bytes: If you do not need s...
mandoc: List::Compare.3pm:1208:87: STYLE: input text line longer than 80 bytes: Except for List::Com...
mandoc: List::Compare.3pm:1216:96: STYLE: input text line longer than 80 bytes: you use \f(CW\*(C`Li...
mandoc: List::Compare.3pm:1243:82: STYLE: input text line longer than 80 bytes: result from a \fIsin...
mandoc: List::Compare.3pm:1249:86: STYLE: input text line longer than 80 bytes: The user selects thi...
mandoc: List::Compare.3pm:1280:108: STYLE: input text line longer than 80 bytes: list (for \f(CW\*(C`...
mandoc: List::Compare.3pm:1284:103: STYLE: input text line longer than 80 bytes: new methods \f(CW\*(...
mandoc: List::Compare.3pm:1302:82: STYLE: input text line longer than 80 bytes: returned are, by def...
mandoc: List::Compare.3pm:1308:101: STYLE: input text line longer than 80 bytes: option. This is don...
mandoc: List::Compare.3pm:1315:98: STYLE: input text line longer than 80 bytes: (\f(CW\*(Aq\-u\*(Aq\...
mandoc: List::Compare.3pm:1329:88: STYLE: input text line longer than 80 bytes: Similarly, the metho...
mandoc: List::Compare.3pm:1340:123: STYLE: input text line longer than 80 bytes: use of methods such ...
mandoc: List::Compare.3pm:1341:82: STYLE: input text line longer than 80 bytes: aliases for \f(CW\*(...
mandoc: List::Compare.3pm:1386:81: STYLE: input text line longer than 80 bytes: test suite which tes...
mandoc: List::Compare.3pm:1388:84: STYLE: input text line longer than 80 bytes: Should you still nee...
mandoc: List::Compare.3pm:1405:102: STYLE: input text line longer than 80 bytes: passing \f(CW\*(Aq\-...
mandoc: List::Compare.3pm:1411:85: STYLE: input text line longer than 80 bytes: the module's templat...
mandoc: List::Compare.3pm:1477:83: STYLE: input text line longer than 80 bytes: discussed the perfor...
mandoc: List::Compare.3pm:1484:83: STYLE: input text line longer than 80 bytes: An April 2004 offer ...
mandoc: List::Compare.3pm:1497:84: STYLE: input text line longer than 80 bytes: Presentations at two...
mandoc: List::Compare.3pm:1499:83: STYLE: input text line longer than 80 bytes: selected to give a t...
mandoc: List::Compare.3pm:1501:83: STYLE: input text line longer than 80 bytes: owes its inspiration...
mandoc: List::Compare.3pm:1509:105: STYLE: input text line longer than 80 bytes: new methods, \f(CW\*...
mandoc: List::Compare.3pm:1511:83: STYLE: input text line longer than 80 bytes: in earlier versions ...
mandoc: List::Compare.3pm:1519:83: STYLE: input text line longer than 80 bytes: patch embodying the ...
mandoc: List::Compare.3pm:1535:88: STYLE: input text line longer than 80 bytes: the Unix \f(CW\*(C`d...
mandoc: List::Compare.3pm:1537:90: STYLE: input text line longer than 80 bytes: methods such as \f(C...
mandoc: List::Compare.3pm:1547:81: STYLE: input text line longer than 80 bytes: are the same or diff...
mandoc: List::Compare.3pm:1566:91: STYLE: input text line longer than 80 bytes: useful functions for...
mandoc: List::Compare.3pm:1567:88: STYLE: input text line longer than 80 bytes: returns the lowest n...
mandoc: List::Compare.3pm:1622:95: STYLE: input text line longer than 80 bytes: Pull request accepte...
mandoc: List::Compare.3pm:1629:82: STYLE: input text line longer than 80 bytes: Please report any bu...
mandoc: List::Compare.3pm:1649:81: STYLE: input text line longer than 80 bytes: PROVIDE THE SOFTWARE...
mandoc: List::Compare.3pm:297:97: STYLE: input text line longer than 80 bytes: because \f(CW\*(Aqab...
mandoc: List::Compare.3pm:316:99: STYLE: input text line longer than 80 bytes: because \f(CW\*(Aqba...
mandoc: List::Compare.3pm:321:85: STYLE: input text line longer than 80 bytes: than one string at a...
mandoc: List::Compare.3pm:356:89: STYLE: input text line longer than 80 bytes: Unlike those two met...
mandoc: List::Compare.3pm:360:81: STYLE: input text line longer than 80 bytes: Determine whether a ...
mandoc: List::Compare.3pm:368:101: STYLE: input text line longer than 80 bytes: In the example above...
mandoc: List::Compare.3pm:572:106: STYLE: input text line longer than 80 bytes: do \fInot\fR count a...
mandoc: List::Compare.3pm:584:92: STYLE: input text line longer than 80 bytes: optionally takes suc...
mandoc: List::Compare.3pm:609:99: STYLE: input text line longer than 80 bytes: passed to the constr...
mandoc: List::Compare.3pm:612:87: STYLE: input text line longer than 80 bytes: Example: \f(CW at Carm...
mandoc: List::Compare.3pm:619:85: STYLE: input text line longer than 80 bytes: If no index position...
mandoc: List::Compare.3pm:625:86: STYLE: input text line longer than 80 bytes: list,\fR provide \f(...
mandoc: List::Compare.3pm:629:84: STYLE: input text line longer than 80 bytes: Example: \f(CW at Don\...
mandoc: List::Compare.3pm:636:87: STYLE: input text line longer than 80 bytes: If no index position...
mandoc: List::Compare.3pm:677:81: STYLE: input text line longer than 80 bytes: passed to the constr...
mandoc: List::Compare.3pm:690:99: STYLE: input text line longer than 80 bytes: If no arguments are ...
mandoc: List::Compare.3pm:696:82: STYLE: input text line longer than 80 bytes: other, provide \f(CW...
mandoc: List::Compare.3pm:699:81: STYLE: input text line longer than 80 bytes: Example: To determi...
mandoc: List::Compare.3pm:708:101: STYLE: input text line longer than 80 bytes: If no arguments are ...
mandoc: List::Compare.3pm:714:91: STYLE: input text line longer than 80 bytes: (\fIi.e.,\fR have no...
mandoc: List::Compare.3pm:727:99: STYLE: input text line longer than 80 bytes: If no arguments are ...
mandoc: List::Compare.3pm:765:97: STYLE: input text line longer than 80 bytes: because \f(CW\*(Aqab...
mandoc: List::Compare.3pm:783:94: STYLE: input text line longer than 80 bytes: because \f(CW\*(Aqje...
mandoc: List::Compare.3pm:788:85: STYLE: input text line longer than 80 bytes: than one string at a...
mandoc: List::Compare.3pm:792:91: STYLE: input text line longer than 80 bytes: Determine in \f(CW\*...
mandoc: List::Compare.3pm:831:81: STYLE: input text line longer than 80 bytes: Determine whether a ...
mandoc: List::Compare.3pm:841:101: STYLE: input text line longer than 80 bytes: In the example above...
mandoc: List::Compare.3pm:885:2: WARNING: empty block: RS
mandoc: List::Compare.3pm:894:87: STYLE: input text line longer than 80 bytes: do \fInot\fR appear ...
mandoc: List::Compare.3pm:965:2: WARNING: empty block: RS
mandoc: List::Compare.3pm:974:99: STYLE: input text line longer than 80 bytes: by passing \f(CW\*(A...
-.-.
Mark a full stop (.) and the exclamation mark (!) with "\&",
if it does not mean an end of a sentence.
This is a preventive action,
the paragraph could be reshaped, e.g., after changes.
When typing, one does not always notice when the line wraps after the
period.
There are too many examples of input lines in manual pages,
that end with an abbreviation point.
This marking is robust, and independent of the position on the line.
It corresponds to "\ " in TeX, and to "@:" in Texinfo.
99:\&... and so forth.
1210:respect to computing the intersection, union, etc. of the two lists.\fR In
1243:result from a \fIsingle\fR form of comparison between two lists. (\fIe.g.,\fR only
1426:(a.k.a. the 'Ram' book), O'Reilly & Associates, 1998, Recipes 4.7 and 4.8.
-.-.
Strings longer than 3/4 of a standard line length (80)
1516 (<https://github.com/nyperlmongers/nyperlhackathon2015/wiki/List\-Compare\-Performance\-Improvements>).
-.-.
Wrong distance between sentences.
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.
N.B.
The number of lines affected can be too large to be in the patch.
99:\&... and so forth.
1210:respect to computing the intersection, union, etc. of the two lists.\fR In
1243:result from a \fIsingle\fR form of comparison between two lists. (\fIe.g.,\fR only
1410:The program was created with Perl 5.6. The use of \fIh2xs\fR to prepare
1426:(a.k.a. the 'Ram' book), O'Reilly & Associates, 1998, Recipes 4.7 and 4.8.
1493:A remark by David H. Adler at a New York Perlmongers meeting in April 2004
1534:Dominus, later maintained by Ned Konz, now maintained by Tye McQueen. Think of
1553:or difference. It does not directly provide methods for intersection and
1566:useful functions for operating on one list at a time. The \f(CW\*(C`min\*(C'\fR function
1633:James E. Keenan (jkeenan at cpan.org). When sending correspondence, please
1641:Copyright (c) 2002\-20 James E. Keenan. United States. All rights reserved.
-.-.
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.
N.B.
The number of lines affected can be too large to be in the patch.
Line 74, length 87
.TH List::Compare 3pm "2022-10-22" "perl v5.34.0" "User Contributed Perl Documentation"
Line 297, length 97
because \f(CW\*(Aqabel\*(Aq\fR is found only in \f(CW at Al\fR which holds position \f(CW0\fR in the
Line 316, length 99
because \f(CW\*(Aqbaker\*(Aq\fR is found in \f(CW at Llist\fR and \f(CW at Rlist\fR, which hold positions
Line 317, length 100
\&\f(CW0\fR and \f(CW1\fR, respectively, in the list of arguments passed to \f(CW\*(C`new()\*(C'\fR.
Line 319, length 105
\&\fBNote:\fR methods \f(CW\*(C`is_member_which()\*(C'\fR and \f(CW\*(C`is_member_which_ref\*(C'\fR test
Line 321, length 85
than one string at a time see the next method, \f(CW\*(C`are_members_which()\*(C'\fR.
Line 354, length 85
\&\fBNote:\fR \f(CW\*(C`are_members_which()\*(C'\fR can take more than one argument;
Line 355, length 110
\&\f(CW\*(C`is_member_which()\*(C'\fR and \f(CW\*(C`is_member_which_ref()\*(C'\fR each take only one argument.
Line 356, length 89
Unlike those two methods, \f(CW\*(C`are_members_which()\*(C'\fR returns a hash reference.
Line 360, length 81
Determine whether a given string can be found in \fIany\fR of the lists passed as
Line 368, length 101
In the example above, \f(CW$found\fR will be \f(CW1\fR because \f(CW\*(Aqabel\*(Aq\fR is found in one
Line 379, length 86
\& $memb_hash_ref = $lc\->are_members_any([ qw| abel baker fargo hilton zebra | ]);
Line 401, length 114
\&\f(CW\*(C`zebra\*(C'\fR's value is \f(CW0\fR because \f(CW\*(C`zebra\*(C'\fR is not found in either of the lists
Line 418, length 82
\&\f(CW\*(C`\*(Aq\-\-accelerated\*(C'\fR as the first argument to the constructor.
Line 439, length 83
\& $lca = List::Compare\->new(\*(Aq\-u\*(Aq, \*(Aq\-a\*(Aq, \e at Llist, \e at Rlist);
Line 445, length 104
\& $lca = List::Compare\->new(\*(Aq\-\-unsorted\*(Aq, \*(Aq\-\-accelerated\*(Aq, \e at Llist, \e at Rlist);
Line 529, length 89
\& $lcm = List::Compare\->new(\*(Aq\-u\*(Aq, \e at Al, \e at Bob, \e at Carmen, \e at Don, \e at Ed);
Line 535, length 98
\& $lcm = List::Compare\->new(\*(Aq\-\-unsorted\*(Aq, \e at Al, \e at Bob, \e at Carmen, \e at Don, \e at Ed);
Line 572, length 106
do \fInot\fR count any unsorted option (\f(CW\*(Aq\-u\*(Aq\fR or \f(CW\*(Aq\-\-unsorted\*(Aq\fR) preceding
Line 580, length 88
\& $lcmex = List::Compare\->new(\*(Aq\-\-unsorted\*(Aq, \e at alpha, \e at beta, \e at gamma);
Line 584, length 92
optionally takes such an argument, \f(CW\*(Aq\-\-unsorted\*(Aq\fR is skipped, \f(CW at alpha\fR
Line 608, length 89
\&\f(CW\*(C`get_unique()\*(C'\fR with that list's index position in the list of arguments
Line 609, length 99
passed to the constructor (not counting any \f(CW\*(Aq\-u\*(Aq\fR or \f(CW\*(Aq\-\-unsorted\*(Aq\fR
Line 612, length 87
Example: \f(CW at Carmen\fR has index position \f(CW2\fR in the constructor's \f(CW at _\fR.
Line 619, length 85
If no index position is passed to \f(CW\*(C`get_unique()\*(C'\fR it will default to 0
Line 625, length 86
list,\fR provide \f(CW\*(C`get_complement()\*(C'\fR with that list's index position in
Line 629, length 84
Example: \f(CW at Don\fR has index position \f(CW3\fR in the constructor's \f(CW at _\fR.
Line 636, length 87
If no index position is passed to \f(CW\*(C`get_complement()\*(C'\fR it will default to
Line 677, length 81
passed to the constructor, provide \f(CW\*(C`is_LsubsetR()\*(C'\fR with the index
Line 690, length 99
If no arguments are passed, \f(CW\*(C`is_LsubsetR()\*(C'\fR defaults to \f(CW\*(C`(0,1)\*(C'\fR and
Line 696, length 82
other, provide \f(CW\*(C`is_LequivalentR\*(C'\fR with their index positions in the
Line 699, length 81
Example: To determine whether \f(CW at Don\fR and \f(CW at Ed\fR are equivalent, call:
Line 708, length 101
If no arguments are passed, \f(CW\*(C`is_LequivalentR\*(C'\fR defaults to \f(CW\*(C`(0,1)\*(C'\fR and
Line 714, length 91
(\fIi.e.,\fR have no members in common), provide \f(CW\*(C`is_LdisjointR\*(C'\fR with their
Line 727, length 99
If no arguments are passed, \f(CW\*(C`is_LdisjointR\*(C'\fR defaults to \f(CW\*(C`(0,1)\*(C'\fR and
Line 765, length 97
because \f(CW\*(Aqabel\*(Aq\fR is found only in \f(CW at Al\fR which holds position \f(CW0\fR in the
Line 783, length 94
because \f(CW\*(Aqjerky\*(Aq\fR is found in \f(CW at Don\fR and \f(CW at Ed\fR, which hold positions
Line 784, length 100
\&\f(CW3\fR and \f(CW4\fR, respectively, in the list of arguments passed to \f(CW\*(C`new()\*(C'\fR.
Line 786, length 105
\&\fBNote:\fR methods \f(CW\*(C`is_member_which()\*(C'\fR and \f(CW\*(C`is_member_which_ref\*(C'\fR test
Line 788, length 85
than one string at a time see the next method, \f(CW\*(C`are_members_which()\*(C'\fR.
Line 792, length 91
Determine in \f(CW\*(C`which\*(C'\fR (if any) of the lists passed to the constructor one or
Line 823, length 85
\&\fBNote:\fR \f(CW\*(C`are_members_which()\*(C'\fR can take more than one argument;
Line 824, length 110
\&\f(CW\*(C`is_member_which()\*(C'\fR and \f(CW\*(C`is_member_which_ref()\*(C'\fR each take only one argument.
Line 825, length 90
\&\f(CW\*(C`are_members_which()\*(C'\fR returns a hash reference; the other methods return
Line 831, length 81
Determine whether a given string can be found in \fIany\fR of the lists passed as
Line 841, length 101
In the example above, \f(CW$found\fR will be \f(CW1\fR because \f(CW\*(Aqabel\*(Aq\fR is found in one
Line 852, length 87
\& $memb_hash_ref = $lcm\->are_members_any([ qw| abel baker fargo hilton zebra | ]);
Line 874, length 110
\&\f(CW\*(C`zebra\*(C'\fR's value will be \f(CW0\fR because \f(CW\*(C`zebra\*(C'\fR is not found in any of the
Line 894, length 87
do \fInot\fR appear in \fIall\fR of the lists (\fIi.e.,\fR all items except those found
Line 967, length 114
.SS "Multiple Accelerated Case: Compare Three or More Lists but Request Only a Single Comparison among the Lists"
Line 968, length 124
.IX Subsection "Multiple Accelerated Case: Compare Three or More Lists but Request Only a Single Comparison among the Lists"
Line 974, length 99
by passing \f(CW\*(Aq\-a\*(Aq\fR or \f(CW\*(C`\*(Aq\-\-accelerated\*(C'\fR as the first argument to
Line 1000, length 84
\& $lcma = List::Compare\->new(\*(Aq\-\-unsorted\*(Aq, \*(Aq\-\-accelerated\*(Aq,
Line 1005, length 99
unsorted option (\f(CW\*(Aq\-u\*(Aq\fR or \f(CW\*(Aq\-\-unsorted\*(Aq\fR) or the accelerated option
Line 1006, length 99
(\f(CW\*(Aq\-a\*(Aq\fR or \f(CW\*(Aq\-\-accelerated\*(Aq\fR) when determining the index position of
Line 1012, length 86
\& $lcmaex = List::Compare\->new(\*(Aq\-\-unsorted\*(Aq, \*(Aq\-\-accelerated\*(Aq,
Line 1041, length 108
optionally takes such an argument, \f(CW\*(Aq\-\-unsorted\*(Aq\fR and \f(CW\*(C`\*(Aq\-\-accelerated\*(C'\fR
Line 1042, length 93
are skipped, \f(CW at alpha\fR is \f(CW0\fR, \f(CW at beta\fR is \f(CW1\fR, and so forth. To get a
Line 1137, length 107
more lists, you can pass \f(CW\*(Aq\-a\*(Aq\fR or \f(CW\*(C`\*(Aq\-\-accelerated\*(C'\fR to the constructor
Line 1155, length 109
If you do not need sorted lists returned, pass \f(CW\*(Aq\-u\*(Aq\fR or \f(CW\*(C`\-\-unsorted\*(C'\fR to the
Line 1160, length 86
\& $lcshau = List::Compare\->new(\*(Aq\-u\*(Aq, \*(Aq\-a\*(Aq, \e%Llist, \e%Rlist);
Line 1161, length 89
\& $lcshmu = List::Compare\->new(\*(Aq\-\-unsorted\*(Aq, \e%Alpha, \e%Beta, \e%Gamma);
Line 1208, length 87
Except for List::Compare's \f(CW\*(C`get_bag()\*(C'\fR method, \fBmultiple instances of
Line 1216, length 96
you use \f(CW\*(C`List::Compare::get_bag()\*(C'\fR to compute a bag holding the two lists do you
Line 1243, length 82
result from a \fIsingle\fR form of comparison between two lists. (\fIe.g.,\fR only
Line 1249, length 86
The user selects this approach by passing the option flag \f(CW\*(Aq\-a\*(Aq\fR to the
Line 1280, length 108
list (for \f(CW\*(C`get_unique()\*(C'\fR and \f(CW\*(C`get_complement()\*(C'\fR) or a specific pair of lists
Line 1284, length 103
new methods \f(CW\*(C`get_shared()\*(C'\fR and \f(CW\*(C`get_nonintersection()\*(C'\fR described in the
Line 1302, length 82
returned are, by default, sorted using Perl's default \f(CW\*(C`sort\*(C'\fR mode:
Line 1308, length 101
option. This is done by calling \f(CW\*(Aq\-u\*(Aq\fR or \f(CW\*(Aq\-\-unsorted\*(Aq\fR as the first
Line 1315, length 98
(\f(CW\*(Aq\-u\*(Aq\fR or \f(CW\*(Aq\-\-unsorted\*(Aq\fR) and \fIthen\fR pass the argument for the
Line 1320, length 87
\&\f(CW\*(C`get_nonintersection()\*(C'\fR in Regular or Accelerated mode since they are
Line 1329, length 88
Similarly, the method \f(CW\*(C`is_RsubsetL()\*(C'\fR is appropriate for the Regular and
Line 1337, length 82
\&'A' and 'B'. Now that you can compare more than two lists at a time, the author
Line 1340, length 123
use of methods such as \f(CW\*(C`get_Aonly()\*(C'\fR, \f(CW\*(C`get_Bonly()\*(C'\fR and \f(CW\*(C`get_AorBonly()\*(C'\fR as
Line 1341, length 82
aliases for \f(CW\*(C`get_unique()\*(C'\fR, \f(CW\*(C`get_complement()\*(C'\fR and
Line 1342, length 94
\&\f(CW\*(C`get_symmetric_difference()\*(C'\fR. However, to guarantee backwards compatibility
Line 1347, length 81
.IX Subsection "List::Compare::SeenHash Discontinued Beginning with Version 0.26"
Line 1386, length 81
test suite which tested List::Compare::SeenHash upon installation be distributed.
Line 1388, length 84
Should you still need List::Compare::SeenHash, use version 0.25 from \s-1CPAN,\s0 or
Line 1405, length 102
passing \f(CW\*(Aq\-u\*(Aq\fR or \f(CW\*(Aq\-\-unsorted\*(Aq\fR as the first argument to the function.
Line 1411, length 85
the module's template installed \f(CW\*(C`require 5.005_62;\*(C'\fR at the top of the
Line 1432, length 88
\&\f(CW\*(C`get_bag()\*(C'\fR method was inspired by Jarkko Hietaniemi's Set::Bag module
Line 1477, length 83
discussed the performance costs entailed in Perl's \f(CW\*(C`sort\*(C'\fR function.
Line 1484, length 83
An April 2004 offer by Kevin Carlson to write an article for \fIThe Perl Journal\fR
Line 1497, length 84
Presentations at two different editions of Yet Another Perl Conference (\s-1YAPC\s0)
Line 1499, length 83
selected to give a talk on List::Compare at \s-1YAPC::NA::2004\s0 in Buffalo. This
Line 1501, length 83
owes its inspiration to one talk at the Buffalo \s-1YAPC\s0 and one earlier talk at
Line 1502, length 89
\&\s-1YAPC::EU::2003\s0 in Paris. In Paris I heard Paul Johnson speak on his \s-1CPAN\s0
Line 1509, length 105
new methods, \f(CW\*(C`get_unique_all\*(C'\fR and \f(CW\*(C`get_complement_all\*(C'\fR. In writing these
Line 1511, length 83
in earlier versions of List::Compare and my other \s-1CPAN\s0 modules. The result?
Line 1516, length 103
(<https://github.com/nyperlmongers/nyperlhackathon2015/wiki/List\-Compare\-Performance\-Improvements>).
Line 1519, length 83
patch embodying the pull request was accepted, leading to \s-1CPAN\s0 version 0.53.
Line 1535, length 88
the Unix \f(CW\*(C`diff\*(C'\fR utility and you're on the right track. Algorithm::Diff
Line 1537, length 90
methods such as \f(CW\*(C`diff\*(C'\fR, which ''computes the smallest set of additions and
Line 1547, length 81
are the same or different by doing a \f(CW\*(C`join\*(C'\fR on each string with a
Line 1566, length 91
useful functions for operating on one list at a time. The \f(CW\*(C`min\*(C'\fR function
Line 1567, length 88
returns the lowest numerical value in a list; the \f(CW\*(C`max\*(C'\fR function returns
Line 1622, length 95
Pull request accepted June 07 2015, correcting errors in \f(CW\*(C`_subset_subengine()\*(C'\fR.
Line 1629, length 82
Please report any bugs by mail to \f(CW\*(C`bug\-List\-Compare at rt.cpan.org\*(C'\fR
Line 1649, length 81
PROVIDE THE SOFTWARE\s0 ''\s-1AS IS\s0'' \s-1WITHOUT WARRANTY OF ANY KIND, EITHER
-.-.
Do not use "\s0" in a string definition but an absolute number,
as the size of the string could be changed.
Then a situation of "\s+X...\s+Y...\s0...\s0" could emerge.
Type size changes have an effect in "troff", but not in "nroff".
25:.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.-.
Do not use more than two space characters between sentences or (better)
only a new line character.
1553:or difference. It does not directly provide methods for intersection and
1566:useful functions for operating on one list at a time. The \f(CW\*(C`min\*(C'\fR function
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
6:.if t .sp .5v
-.-.
Protect a period (.) or an apostrophe (') with '\&' from becoming a
control character, if it could end up at the start of a line
(by splitting the line into more lines).
135:to a function, you may use this 'single hashref' kind of constructor to build a
229:('L' for 'left') is a subset of the second argument passed to the
230:constructor ('R' for 'right').
450:You may use the 'single hashref' constructor format to build a List::Compare
540:You may use the 'single hashref' constructor format to build a List::Compare
1018:The 'single hashref' format may be used to construct a List::Compare
1170:The 'single hashref' form of constructor is also available to build
1271:or in some number of lists between one and all. The meaning of 'union',
1272:\&'intersection' and 'symmetric difference' is conceptually unchanged
1274:considered together. In contrast, the meaning of 'unique', 'complement',
1275:\&'subset' and 'equivalent' changes because these are properties of one list
1337:\&'A' and 'B'. Now that you can compare more than two lists at a time, the author
1426:(a.k.a. the 'Ram' book), O'Reilly & Associates, 1998, Recipes 4.7 and 4.8.
1444:Please note: List::Compare is not concerned with any concept of 'equality'
1455:I learned the truth of the mantra ''Repeated Code is a Mistake'' from a
1478:This led me to ask, ''Why should a user of List::Compare pay this performance
1494:led me to develop the 'single hashref' alternative constructor format,
1530:Algorithm::Diff \- Compute 'intelligent' differences between two files/lists
1537:methods such as \f(CW\*(C`diff\*(C'\fR, which ''computes the smallest set of additions and
1550:Array::Compare is that it allows you to specify how 'whitespace' in an
1608:Set::Array, by Daniel Berger, now maintained by Ron Savage, ''aims to provide
1634:include 'List::Compare' or 'List\-Compare' in your subject line.
1649:PROVIDE THE SOFTWARE\s0 ''\s-1AS IS\s0'' \s-1WITHOUT WARRANTY OF ANY KIND, EITHER
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: file '<stdin>':1516
troff:<stdin>:1516: warning: [page 17, 8.5i]: cannot break line
Bad use of \s0 in a string definition, the string could be resized.
25:.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-------------- next part --------------
--- List::Compare.3pm 2024-06-08 15:47:02.210855643 +0000
+++ List::Compare.3pm.new 2024-06-08 16:35:25.606360351 +0000
@@ -22,7 +22,7 @@
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s+2\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
@@ -96,7 +96,7 @@ The bare essentials:
\& @union = $lc\->get_union;
.Ve
.PP
-\&... and so forth.
+\&...\& and so forth.
.SH "DISCUSSION: Modes and Methods"
.IX Header "DISCUSSION: Modes and Methods"
.SS "Regular Case: Compare Two Lists"
@@ -132,7 +132,7 @@ or
Alternative Constructor
.Sp
If you prefer a more explicit delineation of the types of arguments passed
-to a function, you may use this 'single hashref' kind of constructor to build a
+to a function, you may use this \&'single hashref' kind of constructor to build a
List::Compare object:
.Sp
.Vb 1
@@ -226,8 +226,8 @@ parallel methods:
\&\f(CW\*(C`is_LsubsetR()\*(C'\fR
.Sp
Return a true value if the first argument passed to the constructor
-('L' for 'left') is a subset of the second argument passed to the
-constructor ('R' for 'right').
+('L' for \&'left') is a subset of the second argument passed to the
+constructor ('R' for \&'right').
.Sp
.Vb 1
\& $LR = $lc\->is_LsubsetR;
@@ -447,7 +447,7 @@ or
.IP "\(bu" 4
Alternative Constructor
.Sp
-You may use the 'single hashref' constructor format to build a List::Compare
+You may use the \&'single hashref' constructor format to build a List::Compare
object calling for the Accelerated mode:
.Sp
.Vb 4
@@ -537,7 +537,7 @@ or
.IP "\(bu" 4
Alternative Constructor
.Sp
-You may use the 'single hashref' constructor format to build a List::Compare
+You may use the \&'single hashref' constructor format to build a List::Compare
object to process three or more lists at once:
.Sp
.Vb 3
@@ -1015,7 +1015,7 @@ Example:
.IP "\(bu" 4
Alternative Constructor
.Sp
-The 'single hashref' format may be used to construct a List::Compare
+The \&'single hashref' format may be used to construct a List::Compare
object which calls for accelerated processing of three or more lists at once:
.Sp
.Vb 4
@@ -1167,7 +1167,7 @@ array index of a particular seen-hash re
.IP "\(bu" 4
Alternative Constructor
.Sp
-The 'single hashref' form of constructor is also available to build
+The \&'single hashref' form of constructor is also available to build
List::Compare objects where seen-hashes are used as arguments:
.Sp
.Vb 4
@@ -1207,7 +1207,7 @@ lists.
.PP
Except for List::Compare's \f(CW\*(C`get_bag()\*(C'\fR method, \fBmultiple instances of
an element in a given list count only once with
-respect to computing the intersection, union, etc. of the two lists.\fR In
+respect to computing the intersection, union, etc.\& of the two lists.\fR In
particular, List::Compare considers two lists as equivalent if each element
of the first list can be found in the second list and \fIvice versa\fR.
\&'Equivalence' in this usage takes no note of the frequency with which
@@ -1240,8 +1240,9 @@ Accelerated Mode
.Sp
The current implementation of List::Compare offers you the option of
getting even faster results \fIprovided\fR that you only need the
-result from a \fIsingle\fR form of comparison between two lists. (\fIe.g.,\fR only
-the union \*(-- nothing else). In the Accelerated mode, List::Compare's
+result from a \fIsingle\fR form of comparison between two lists.
+(\fIe.g.,\fR only the union \*(-- nothing else).
+In the Accelerated mode, List::Compare's
initializer does no computation and its constructor stores only references
to the two source lists. All computation needed to report results is
deferred to the method calls.
@@ -1268,11 +1269,11 @@ have been passed to the constructor and
As described in the Synopsis above, comparing more than two lists at a time
offers you a wider, more complex palette of comparison methods.
Individual items may appear in just one source list, in all the source lists,
-or in some number of lists between one and all. The meaning of 'union',
-\&'intersection' and 'symmetric difference' is conceptually unchanged
+or in some number of lists between one and all. The meaning of \&'union',
+\&'intersection' and \&'symmetric difference' is conceptually unchanged
when you move to multiple lists because these are properties of all the lists
-considered together. In contrast, the meaning of 'unique', 'complement',
-\&'subset' and 'equivalent' changes because these are properties of one list
+considered together. In contrast, the meaning of \&'unique', \&'complement',
+\&'subset' and \&'equivalent' changes because these are properties of one list
compared with another or with all the other lists combined.
.Sp
List::Compare takes this complexity into account by allowing you to pass
@@ -1334,7 +1335,7 @@ re-code.
.PP
In List::Compare v0.11 and earlier, the author provided aliases for various
methods based on the supposition that the source lists would be referred to as
-\&'A' and 'B'. Now that you can compare more than two lists at a time, the author
+\&'A' and \&'B'. Now that you can compare more than two lists at a time, the author
feels that it would be more appropriate to refer to the elements of two-argument
lists as the left-hand and right-hand elements. Hence, we are discouraging the
use of methods such as \f(CW\*(C`get_Aonly()\*(C'\fR, \f(CW\*(C`get_Bonly()\*(C'\fR and \f(CW\*(C`get_AorBonly()\*(C'\fR as
@@ -1407,9 +1408,10 @@ Please see the documentation for List::C
import its functions into your main package.
.SH "ASSUMPTIONS AND QUALIFICATIONS"
.IX Header "ASSUMPTIONS AND QUALIFICATIONS"
-The program was created with Perl 5.6. The use of \fIh2xs\fR to prepare
-the module's template installed \f(CW\*(C`require 5.005_62;\*(C'\fR at the top of the
-module. This has been commented out in the actual module as the code
+The program was created with Perl 5.6.
+The use of \fIh2xs\fR to prepare the module's template installed
+\f(CW\*(C`require 5.005_62;\*(C'\fR at the top of the module.
+This has been commented out in the actual module as the code
appears to be compatible with earlier versions of Perl; how earlier the
author cannot say. In particular, the author would like the module to
be installable on older versions of MacPerl. As is, the author has
@@ -1423,7 +1425,7 @@ tested and installed.
.IX Subsection "The Code Itself"
List::Compare is based on code presented by Tom Christiansen & Nathan
Torkington in \fIPerl Cookbook\fR <http://www.oreilly.com/catalog/cookbook/>
-(a.k.a. the 'Ram' book), O'Reilly & Associates, 1998, Recipes 4.7 and 4.8.
+(a.k.a.\& the \&'Ram' book), O'Reilly & Associates, 1998, Recipes 4.7 and 4.8.
Similar code is presented in the Camel book: \fIProgramming Perl\fR, by Larry
Wall, Tom Christiansen, Jon Orwant.
<http://www.oreilly.com/catalog/pperl3/>, 3rd ed, O'Reilly & Associates,
@@ -1441,7 +1443,7 @@ With the addition of the Accelerated, Mu
modes, List::Compare expands considerably in both size and capabilities.
Nonetheless, Tom and Nat's \fICookbook\fR code still lies at its core:
the use of hashes as look-up tables to record elements seen in lists.
-Please note: List::Compare is not concerned with any concept of 'equality'
+Please note: List::Compare is not concerned with any concept of \&'equality'
among lists which hinges upon the frequency with which, or the order in
which, elements appear in the lists to be compared. If this does not
meet your needs, you should look elsewhere or write your own module.
@@ -1452,7 +1454,7 @@ module while preparing an introductory l
School University's Computer Instruction Center in April-May 2002. I was
comparing lists left and right. When I found myself writing very similar
functions in different scripts, I knew a module was lurking somewhere.
-I learned the truth of the mantra ''Repeated Code is a Mistake'' from a
+I learned the truth of the mantra \&''Repeated Code is a Mistake'' from a
2001 talk by Mark-Jason Dominus <http://perl.plover.com/> to the New York
Perlmongers <http://ny.pm.org/>.
See <http://www.perl.com/pub/a/2000/11/repair3.html>.
@@ -1475,7 +1477,7 @@ October 2003 prompted me to begin planni
.PP
In a November 2003 Perl Seminar New York presentation, Ben Holtzman
discussed the performance costs entailed in Perl's \f(CW\*(C`sort\*(C'\fR function.
-This led me to ask, ''Why should a user of List::Compare pay this performance
+This led me to ask, \&''Why should a user of List::Compare pay this performance
cost if he or she doesn't need a human-readable list as a result (as
would be the case if the list returned were used as the input into some
other function)?'' This led to the development of List::Compare's
@@ -1490,8 +1492,8 @@ to accept both kinds of arguments, I ada
manner. This meant that List::Compare::SeenHash and its related installation
tests could be deprecated and deleted from the \s-1CPAN\s0 distribution.
.PP
-A remark by David H. Adler at a New York Perlmongers meeting in April 2004
-led me to develop the 'single hashref' alternative constructor format,
+A remark by David H.\& Adler at a New York Perlmongers meeting in April 2004
+led me to develop the \&'single hashref' alternative constructor format,
introduced in version 0.29 the following month.
.PP
Presentations at two different editions of Yet Another Perl Conference (\s-1YAPC\s0)
@@ -1513,11 +1515,12 @@ List::Compare's test suite grew by over
.PP
At the Second New York Perl Hackathon (May 02 2015), a project was created to
request performance improvements in certain List::Compare functions
-(<https://github.com/nyperlmongers/nyperlhackathon2015/wiki/List\-Compare\-Performance\-Improvements>).
+(<https://github.com/\:nyperlmongers/\:nyperlhackathon2015/\:wiki/\:List\
+\-Compare\-Performance\-Improvements>).
Hackathon participant Michael Rawson submitted a pull request with changes to
List::Compare::Base::_Auxiliary. After these revisions were benchmarked, a
patch embodying the pull request was accepted, leading to \s-1CPAN\s0 version 0.53.
-.SS "If You Like List::Compare, You'll Love ..."
+.SS "If You Like List::Compare, You'll Love ...\&"
.IX Subsection "If You Like List::Compare, You'll Love ..."
While preparing this module for distribution via \s-1CPAN, I\s0 had occasion to
study a number of other modules already available on \s-1CPAN.\s0 Each of these
@@ -1527,14 +1530,16 @@ Cookbook code repeatedly. Here is a bri
these modules. (\fBWarning:\fR The following discussion is only valid as
of June 2002. Some of these modules may have changed since then.)
.IP "\(bu" 4
-Algorithm::Diff \- Compute 'intelligent' differences between two files/lists
+Algorithm::Diff \- Compute \&'intelligent' differences between two files/lists
(<http://search.cpan.org/dist/Algorithm\-Diff/>)
.Sp
Algorithm::Diff is a sophisticated module originally written by Mark-Jason
-Dominus, later maintained by Ned Konz, now maintained by Tye McQueen. Think of
-the Unix \f(CW\*(C`diff\*(C'\fR utility and you're on the right track. Algorithm::Diff
-exports
-methods such as \f(CW\*(C`diff\*(C'\fR, which ''computes the smallest set of additions and
+Dominus, later maintained by Ned Konz, now maintained by Tye McQueen.
+Think of the Unix \f(CW\*(C`diff\*(C'\fR utility and you're on the right
+track.
+Algorithm::Diff exports
+methods such as \f(CW\*(C`diff\*(C'\fR, which \&''computes the smallest set of
+additions and
deletions necessary to turn the first sequence into the second, and returns a
description of these changes.'' Algorithm::Diff is mainly concerned with the
sequence of elements within two lists. It does not export functions for
@@ -1544,14 +1549,14 @@ Array::Compare \- Perl extension for com
(<http://search.cpan.org/dist/Array\-Compare/>)
.Sp
Array::Compare, by Dave Cross, asks whether two arrays
-are the same or different by doing a \f(CW\*(C`join\*(C'\fR on each string with a
-separator character and comparing the resulting strings. Like
+are the same or different by doing a \f(CW\*(C`join\*(C'\fR on each string
+with a separator character and comparing the resulting strings. Like
List::Compare, it is an object-oriented module. A sophisticated feature of
-Array::Compare is that it allows you to specify how 'whitespace' in an
+Array::Compare is that it allows you to specify how \&'whitespace' in an
array (an element which is undefined, the empty string, or whitespace
within an element) should be evaluated for purpose of determining equality
-or difference. It does not directly provide methods for intersection and
-union.
+or difference.
+It does not directly provide methods for intersection and union.
.IP "\(bu" 4
Data::Compare \- compare perl data structures
(<http://search.cpan.org/dist/Data\-Compare/>)
@@ -1563,7 +1568,8 @@ List::Util \- A selection of general-uti
(<http://search.cpan.org/dist/Scalar\-List\-Utils/>)
.Sp
List::Util, by Graham Barr, exports a variety of simple,
-useful functions for operating on one list at a time. The \f(CW\*(C`min\*(C'\fR function
+useful functions for operating on one list at a time.
+The \f(CW\*(C`min\*(C'\fR function
returns the lowest numerical value in a list; the \f(CW\*(C`max\*(C'\fR function returns
the highest value; and so forth. List::Compare differs from List::Util in
that it is object-oriented and that it works on two strings at a time
@@ -1605,7 +1611,7 @@ Set::Array \- Arrays as objects with lot
comparisons) and support for method chaining.
(<http://search.cpan.org/dist/Set\-Array/>)
.Sp
-Set::Array, by Daniel Berger, now maintained by Ron Savage, ''aims to provide
+Set::Array, by Daniel Berger, now maintained by Ron Savage, \&''aims to provide
built-in methods for operations that people are always asking how to do,and
which already exist in languages like Ruby.'' Among the many methods in
this module are some for intersection, union, etc. To install Set::Array,
@@ -1630,15 +1636,15 @@ Please report any bugs by mail to \f(CW\
or through the web interface at <http://rt.cpan.org>.
.SH "AUTHOR"
.IX Header "AUTHOR"
-James E. Keenan (jkeenan at cpan.org). When sending correspondence, please
-include 'List::Compare' or 'List\-Compare' in your subject line.
+James E.\& Keenan (jkeenan at cpan.org). When sending correspondence, please
+include \&'List::Compare' or \&'List\-Compare' in your subject line.
.PP
Creation date: May 20, 2002. Last modification date: August 16 2020.
.PP
Development repository: <https://github.com/jkeenan/list\-compare>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-Copyright (c) 2002\-20 James E. Keenan. United States. All rights reserved.
+Copyright (c) 2002\-20 James E.\& Keenan. United States. All rights reserved.
This is free software and may be distributed under the same terms as Perl
itself.
.SH "DISCLAIMER OF WARRANTY"
More information about the pkg-perl-maintainers
mailing list