This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlutil updates and cleanup
authorDan Book <grinnz@grinnz.com>
Tue, 6 Oct 2020 23:34:33 +0000 (19:34 -0400)
committerKarl Williamson <khw@cpan.org>
Wed, 7 Oct 2020 02:23:08 +0000 (20:23 -0600)
- Add missing encguess, json_pp, and streamzip utilities
- Normalize item entries for utilities so they are equally visible and linkable
- Normalize usage of F<> on unlinked executables
- Normalize linking to referenced modules
- Simplify links with duplicate text
- Clean up SEE ALSO

pod/perlutil.pod
t/porting/known_pod_issues.dat

index 2703815..c5b60e9 100644 (file)
@@ -17,9 +17,9 @@ if appropriate.
 
 =over 3
 
-=item L<perldoc|perldoc>
+=item L<perldoc>
 
-The main interface to Perl's documentation is C<perldoc>, although
+The main interface to Perl's documentation is F<perldoc>, although
 if you're reading this, it's more than likely that you've already found
 it. F<perldoc> will extract and format the documentation from any file
 in the current directory, any Perl module installed on the system, or
@@ -27,7 +27,9 @@ any of the standard documentation pages, such as this one. Use
 C<perldoc E<lt>nameE<gt>> to get information on any of the utilities
 described in this document.
 
-=item L<pod2man|pod2man> and L<pod2text|pod2text>
+=item L<pod2man>
+
+=item L<pod2text>
 
 If it's run from a terminal, F<perldoc> will usually call F<pod2man> to
 translate POD (Plain Old Documentation - see L<perlpod> for an
@@ -35,31 +37,31 @@ explanation) into a manpage, and then run F<man> to display it; if
 F<man> isn't available, F<pod2text> will be used instead and the output
 piped through your favourite pager.
 
-=item L<pod2html|pod2html>
+=item L<pod2html>
 
 As well as these two, there is another converter: F<pod2html> will
 produce HTML pages from POD.
 
-=item L<pod2usage|pod2usage>
+=item L<pod2usage>
 
 If you just want to know how to use the utilities described here,
 F<pod2usage> will just extract the "USAGE" section; some of
 the utilities will automatically call F<pod2usage> on themselves when
 you call them with C<-help>.
 
-=item L<podchecker|podchecker>
+=item L<podchecker>
 
 If you're writing your own documentation in POD, the F<podchecker>
 utility will look for errors in your markup.
 
-=item L<splain|splain>
+=item L<splain>
 
 F<splain> is an interface to L<perldiag> - paste in your error message
 to it, and it'll explain it for you.
 
-=item C<roffitall>
+=item F<roffitall>
 
-The C<roffitall> utility is not installed on your system but lives in
+The F<roffitall> utility is not installed on your system but lives in
 the F<pod/> directory of your Perl source kit; it converts all the
 documentation from the distribution to F<*roff> format, and produces a
 typeset PostScript or text file of the whole lot.
@@ -68,15 +70,21 @@ typeset PostScript or text file of the whole lot.
 
 =head2 Converters
 
+=over 3
+
+=item L<pl2pm>
+
 To help you convert legacy programs to more modern Perl, the
-L<pl2pm|pl2pm> utility will help you convert old-style Perl 4 libraries
+F<pl2pm> utility will help you convert old-style Perl 4 libraries
 to new-style Perl5 modules.
 
+=back
+
 =head2 Administration
 
 =over 3
 
-=item L<libnetcfg|libnetcfg>
+=item L<libnetcfg>
 
 To display and change the libnet configuration run the libnetcfg command.
 
@@ -96,7 +104,7 @@ and in particular, extending Perl with C.
 
 =over 3
 
-=item L<perlbug|perlbug>
+=item L<perlbug>
 
 F<perlbug> used to be the recommended way to report bugs in the perl
 interpreter itself or any of the standard library modules back to the
@@ -109,7 +117,7 @@ This program provides an easy way to send a thank-you message back to the
 authors and maintainers of perl. It's just F<perlbug> installed under
 another name.
 
-=item L<h2ph|h2ph>
+=item L<h2ph>
 
 Back before Perl had the XS system for connecting with C libraries,
 programmers used to get library constants by reading through the C
@@ -118,7 +126,7 @@ around - the F<.ph> file should be created by running F<h2ph> on the
 corresponding F<.h> file. See the F<h2ph> documentation for more on how
 to convert a whole bunch of header files at once.
 
-=item L<h2xs|h2xs>
+=item L<h2xs>
 
 F<h2xs> converts C header files into XS modules, and will try and write
 as much glue between C libraries and Perl modules as it can. It's also
@@ -144,11 +152,11 @@ necessary to let Perl access those functions.
 =item L<prove>
 
 F<prove> is a command-line interface to the test-running functionality
-of F<Test::Harness>.  It's an alternative to C<make test>.
+of L<Test::Harness>.  It's an alternative to C<make test>.
 
 =item L<corelist>
 
-A command-line front-end to C<Module::CoreList>, to query what modules
+A command-line front-end to L<Module::CoreList>, to query what modules
 were shipped with given versions of perl.
 
 =back
@@ -160,9 +168,17 @@ came along modules included in the perl distribution.
 
 =over 3
 
+=item L<encguess>
+
+F<encguess> will attempt to guess the character encoding of files.
+
+=item L<json_pp>
+
+F<json_pp> is a pure Perl JSON converter and formatter.
+
 =item L<piconv>
 
-B<piconv> is a Perl version of B<iconv>, a character encoding converter
+F<piconv> is a Perl version of L<iconv(1)>, a character encoding converter
 widely available for various Unixen today.  This script was primarily a
 technology demonstrator for Perl v5.8.0, but you can use piconv in the
 place of iconv for virtually any case.
@@ -175,7 +191,7 @@ F<ptar> is a tar-like program, written in pure Perl.
 
 F<ptardiff> is a small utility that produces a diff between an extracted
 archive and an unextracted one. (Note that this utility requires the
-C<Text::Diff> module to function properly; this module isn't distributed
+L<Text::Diff> module to function properly; this module isn't distributed
 with perl, but is available from the CPAN.)
 
 =item L<ptargrep>
@@ -185,12 +201,16 @@ in a tar archive.
 
 =item L<shasum>
 
-This utility, that comes with the C<Digest::SHA> module, is used to print
+This utility, that comes with the L<Digest::SHA> module, is used to print
 or verify SHA checksums.
 
+=item L<streamzip>
+
+F<streamzip> compresses data streamed to STDIN into a streamed zip container.
+
 =item L<zipdetails>
 
-L<zipdetails> displays information about the internal record structure of the zip file.
+F<zipdetails> displays information about the internal record structure of the zip file.
 It is not concerned with displaying any details of the compressed data stored in the zip file.
 
 =back
@@ -212,19 +232,18 @@ a lot more.  It is similar to the command line mode of the L<CPAN> module,
 
 =item L<instmodsh>
 
-A little interface to ExtUtils::Installed to examine installed modules,
+A little interface to L<ExtUtils::Installed> to examine installed modules,
 validate your packlists and even create a tarball from an installed module.
 
 =back
 
 =head1 SEE ALSO
 
-L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>,
-L<pod2html|pod2html>, L<pod2usage|pod2usage>,
-L<podchecker|podchecker>, L<splain|splain>, L<perldiag>,
-C<roffitall|roffitall>, L<File::Find|File::Find>, L<pl2pm|pl2pm>,
-L<perlbug|perlbug>, L<h2ph|h2ph>, L<h2xs|h2xs>, L<enc2xs>,
-L<xsubpp>, L<cpan>, L<instmodsh>, L<piconv>, L<prove>, L<corelist>, L<ptar>,
-L<ptardiff>, L<shasum>, L<zipdetails>
+L<perldoc>, L<pod2man>, L<pod2text>, L<pod2html>, L<pod2usage>,
+L<podchecker>, L<splain>, L<pl2pm>,
+L<perlbug>, L<h2ph>, L<h2xs>, L<enc2xs>,
+L<xsubpp>, L<cpan>, L<encguess>, L<instmodsh>, L<json_pp>,
+L<piconv>, L<prove>, L<corelist>, L<ptar>,
+L<ptardiff>, L<shasum>, L<streamzip>, L<zipdetails>
 
 =cut
index 00d38c0..8eb9fc5 100644 (file)
@@ -329,6 +329,7 @@ Test::Inline
 Test::MockObject
 Test::Unit
 Text::Autoformat
+Text::Diff
 Text::Soundex
 Text::Template
 Text::Unidecode