diff options
author | Dan Book <grinnz@grinnz.com> | 2020-10-06 19:34:33 -0400 |
---|---|---|
committer | Karl Williamson <khw@cpan.org> | 2020-10-06 20:23:08 -0600 |
commit | 43f856bae111d54f354ee7393baba1cf1617a769 (patch) | |
tree | 2602b9a0bc20ef70fb5bb74946ad997d7f650519 /pod | |
parent | dbb22d67806a4b7a54e401a9d749539c26d72408 (diff) | |
download | perl-43f856bae111d54f354ee7393baba1cf1617a769.tar.gz |
perlutil updates and cleanup
- 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
Diffstat (limited to 'pod')
-rw-r--r-- | pod/perlutil.pod | 75 |
1 files changed, 47 insertions, 28 deletions
diff --git a/pod/perlutil.pod b/pod/perlutil.pod index 2703815464..c5b60e9d29 100644 --- a/pod/perlutil.pod +++ b/pod/perlutil.pod @@ -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 |