Mailing List Archive

(I thought DProf made it standard; am I confused?)

* Various miscellaneous updates

* Removed perlovl from perl.pod in lieu of overload.pm pod

* Added much of the Modules file into perlmod. I'm not
sure whether this is the right place for it.

* All documented modules are listed in perlmod. Most are
not documented. At this point, installman will bitch
loudly about them and remove their previously bogus
podpages. Please do something about this.

ExtUtils::Liblist.pm SubstrHash.pm Text::Tabs.pm
ExtUtils::Mkbootstrap.pm Sys::Hostname.pm Text::Wrap.pm
ExtUtils::Miniperl.pm Sys::Syslog.pm TieHash.pm
Math::BigFloat.pm Term::Cap.pm Time::Local.pm
Math::BigInt.pm Term::Complete.pm NDBM_File.pm
Math::Complex.pm Test::Harness.pm ODBM_File.pm
Search::Dict.pm Text::ParseWords.pm (POSIX.pm)
Shell.pm Text::Soundex.pm SDBM_File.pm

POSIX of course isn't really wrong. I'm not sure about the others.

* This gives me fits:

1;
__END__
=head1 NAME

Devel::SelfStubber - generate stubs for a SelfLoading module

Because it forces me to parse suboptimally. Why can't it
be written this way so I can use paragraph mode?

1;
__END__

=head1 NAME

Devel::SelfStubber - generate stubs for a SelfLoading module

Anyway, here's a patch:

diff -c -r old/pod/perl.pod new/pod/perl.pod
*** old/pod/perl.pod Sat Nov 18 15:23:58 1995
--- new/pod/perl.pod Sun Dec 10 07:00:53 1995
***************
*** 33,39 ****
perlxstut Perl XS tutorial
perlguts Perl internal functions for those doing extensions
perlcall Perl calling conventions from C
- perlovl Perl overloading semantics
perlembed Perl how to embed perl in your C or C++ app
perlpod Perl plain old documentation
perlbook Perl book information
--- 33,38 ----
diff -c -r old/pod/perlbot.pod new/pod/perlbot.pod
*** old/pod/perlbot.pod Fri Nov 10 15:27:33 1995
--- new/pod/perlbot.pod Sat Dec 9 12:36:51 1995
***************
*** 2,8 ****

perlbot - Bag'o Object Tricks (the BOT)

! =head1 INTRODUCTION

The following collection of tricks and hints is intended to whet curious
appetites about such things as the use of instance variables and the
--- 2,8 ----

perlbot - Bag'o Object Tricks (the BOT)

! =head1 DESCRIPTION

The following collection of tricks and hints is intended to whet curious
appetites about such things as the use of instance variables and the
diff -c -r old/pod/perldata.pod new/pod/perldata.pod
*** old/pod/perldata.pod Sat Nov 18 15:23:59 1995
--- new/pod/perldata.pod Sun Dec 10 04:01:28 1995
***************
*** 138,144 ****
use it as if it were defined, but prior to that you can use the
defined() operator to determine whether the value is defined or not.

! To find out whether a given string is a valid non-zero number, it's usally
enough to test it against both numeric 0 and also lexical "0" (although
this will cause B<-w> noises). That's because strings that aren't
numbers count as 0, just as the do in I<awk>:
--- 138,144 ----
use it as if it were defined, but prior to that you can use the
defined() operator to determine whether the value is defined or not.

! To find out whether a given string is a valid non-zero number, it's usually
enough to test it against both numeric 0 and also lexical "0" (although
this will cause B<-w> noises). That's because strings that aren't
numbers count as 0, just as the do in I<awk>:
***************
*** 146,151 ****
--- 146,162 ----
if ($str == 0 && $str ne "0") {
warn "That doesn't look like a number";
}
+
+ That's usually preferable because otherwise you won't treat IEEE notations
+ like C<NaN> or C<Infinity> properly. At other times you might prefer to
+ use a regular expression to check whether data is numeric. See L<perlre>
+ for details on regular expressions.
+
+ warn "not a whole number" unless /^\d+$/;
+ warn "not an integer" unless /^[+-]?\d+$/
+ warn "not a decimal number" unless /^[+-]?\d+\.?\d*$/
+ warn "not a C float"
+ unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;

The length of an array is a scalar value. You may find the length of
array @days by evaluating C<$#days>, as in B<csh>. (Actually, it's not
diff -c -r old/pod/perldsc.pod new/pod/perldsc.pod
*** old/pod/perldsc.pod Sat Nov 18 15:24:22 1995
--- new/pod/perldsc.pod Sat Dec 9 17:12:15 1995
***************
*** 1,8 ****
! =head1 TITLE

perldsc - Manipulating Complex Data Structures in Perl

! =head1 INTRODUCTION

The single feature most sorely lacking in the Perl programming language
prior to its 5.0 release was complex data structures. Even without direct
--- 1,8 ----
! =head1 NAME

perldsc - Manipulating Complex Data Structures in Perl

! =head1 DESCRIPTION

The single feature most sorely lacking in the Perl programming language
prior to its 5.0 release was complex data structures. Even without direct
diff -c -r old/pod/perlform.pod new/pod/perlform.pod
*** old/pod/perlform.pod Sat Nov 18 15:23:59 1995
--- new/pod/perlform.pod Sun Dec 10 03:52:55 1995
***************
*** 310,314 ****

Lexical variables (declared with "my") are not visible within a
format unless the format is declared within the scope of the lexical
! variable. (They weren't visible at all before version 5.001.) See
L<perlfunc/my> for other issues.
--- 310,315 ----

Lexical variables (declared with "my") are not visible within a
format unless the format is declared within the scope of the lexical
! variable. (They weren't visible at all before version 5.001.) Furthermore,
! lexical aliases will not be compiled correctly: see
L<perlfunc/my> for other issues.
diff -c -r old/pod/perllol.pod new/pod/perllol.pod
*** old/pod/perllol.pod Sat Nov 18 15:24:22 1995
--- new/pod/perllol.pod Sat Dec 9 17:25:12 1995
***************
*** 1,8 ****
! =head1 TITLE

perlLoL - Manipulating Lists of Lists in Perl

! =head1 Declaration and Access

The simplest thing to build is a list of lists (sometimes called an array
of arrays). It's reasonably easy to understand, and almost everything
--- 1,10 ----
! =head1 NAME

perlLoL - Manipulating Lists of Lists in Perl

! =head1 DESCRIPTION
!
! =head1 Declaration and Access of Lists of Lists

The simplest thing to build is a list of lists (sometimes called an array
of arrays). It's reasonably easy to understand, and almost everything
diff -c -r old/pod/perlmod.pod new/pod/perlmod.pod
*** old/pod/perlmod.pod Sat Nov 18 15:24:03 1995
--- new/pod/perlmod.pod Sun Dec 10 07:20:10 1995
***************
*** 295,300 ****
--- 295,304 ----

Pragma to request less of something from the compiler

+ =item C<overload>
+
+ Pragma for overloading operators
+
=item C<sigtrap>

Pragma to enable stack backtrace on unexpected signals
***************
*** 315,322 ****
manner with respect to namespace pollution because they use the
Exporter module. See their own documentation for details.

! To find out all the modules installed on your system, do this:

find `perl -e 'print "@INC"'` -name '*.pm' -print

They should all have their own documentation installed and accessible via
--- 319,424 ----
manner with respect to namespace pollution because they use the
Exporter module. See their own documentation for details.

! =over 12

+ =item AnyDBM_File
+ provide framework for multiple DBMs
+
+ =item AutoLoader
+ load functions only on demand
+
+ =item AutoSplit
+ split a package for autoloading
+
+ =item Benchmark
+ benchmark running times of code
+
+ =item Carp
+ warn of errors (from perspective of caller)
+
+ =item Config
+ access Perl configuration option
+
+ =item Cwd
+ get pathname of current working directory
+
+ =item DB_File
+ Perl access to Berkeley DB
+
+ =item Devel::SelfStubber
+ generate stubs for a SelfLoading module
+
+ =item DynaLoader
+ Dynamically load C libraries into Perl code
+
+ =item English
+ use nice English (or awk) names for ugly punctuation variables
+
+ =item Env
+ perl module that imports environment variables
+
+ =item Exporter
+ provide inport/export controls for Perl modules
+
+ =item ExtUtils::MakeMaker
+ create an extension Makefile
+
+ =item ExtUtils::Manifest
+ utilities to write and check a MANIFEST file
+
+ =item Fcntl
+ load the C Fcntl.h defines
+
+ =item File::Basename
+ parse file specifications
+
+ =item File::CheckTree
+ run many filetest checks on a tree
+
+ =item File::Find
+ traverse a file tree
+
+ =item FileHandle
+ supply object methods for filehandles
+
+ =item File::Path
+ create or remove a series of directories
+
+ =item Getopt::Long
+ extended getopt processing
+
+ =item Getopt::Std
+ Process single-character switches with switch clustering
+
+ =item I18N::Collate
+ compare 8-bit scalar data according to the current locale
+
+ =item IPC::Open2
+ a process for both reading and writing
+
+ =item IPC::Open3
+ open a process for reading, writing, and error handling
+
+ =item Net::Ping
+ check a host for upness
+
+ =item POSIX
+ Perl interface to IEEE Std 1003.1
+
+ =item SelfLoader
+ load functions only on demand
+
+ =item Socket
+ load the C socket.h defines and structure manipulators
+
+ =item Text::Abbrev
+ rceate an abbreviation table from a list
+
+ =back
+
+ To find out I<all> the modules installed on your system, including
+ those without documentation or outside the standard release, do this:
+
find `perl -e 'print "@INC"'` -name '*.pm' -print

They should all have their own documentation installed and accessible via
***************
*** 328,342 ****
dynamically loaded into Perl if and when you need them. Supported
extension modules include the Socket, Fcntl, and POSIX modules.

! Many popular C extension modules
! do not come bundled (at least, not completely)
! due to their size, volatility, or simply lack of time for adequate testing
! and configuration across the multitude of platforms on which Perl was
! beta-tested. You are encouraged to look for them in archie(1L), the Perl
! FAQ or Meta-FAQ, the WWW page, and even with their authors before randomly
! posting asking for their present condition and disposition.

! =head2 CPAN

CPAN stands for the Comprehensive Perl Archive Network. This is a globally
replicated collection of all known Perl materials, including hundreds
--- 430,444 ----
dynamically loaded into Perl if and when you need them. Supported
extension modules include the Socket, Fcntl, and POSIX modules.

! Many popular C extension modules do not come bundled (at least, not
! completely) due to their size, volatility, or simply lack of time for
! adequate testing and configuration across the multitude of platforms on
! which Perl was beta-tested. You are encouraged to look for them in
! archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
! authors before randomly posting asking for their present condition and
! disposition.

! =head1 CPAN

CPAN stands for the Comprehensive Perl Archive Network. This is a globally
replicated collection of all known Perl materials, including hundreds
***************
*** 484,486 ****
--- 586,956 ----

For an up-to-date listing of CPAN sites,
see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/.
+
+
+ =head1 Modules: Creation, Use and Abuse
+
+ (The following section is borrowed directly from Tim Bunce's modules
+ file.)
+
+
+ Perl 5 implements a class using a package, but the presence of a
+ package doesn't imply the presence of a class. A package is just a
+ namespace. A class is a package that provides subroutines that can be
+ used as methods. A method is just a subroutine that expects, as its
+ first argument, either the name of a package (for "static" methods),
+ or a reference to something (for "virtual" methods).
+
+ A module is a file that (by convention) provides a class of the same
+ name (sans the .pm), plus an import method in that class that can be
+ called to fetch exported symbols. This module may implement some of
+ its methods by loading dynamic C or C++ objects, but that should be
+ totally transparent to the user of the module. Likewise, the module
+ might set up an AUTOLOAD function to slurp in subroutine definitions on
+ demand, but this is also transparent. Only the .pm file is required to
+ exist.
+
+ =head2 Guidelines for Module Creation
+
+ =over 4
+
+ =item Do similar modules already exist in some form?
+
+ If so, please try to reuse the existing modules either in whole or
+ by inheriting useful features into a new class. If this is not
+ practical try to get together with the module authors to work on
+ extending or enhancing the functionality of the existing modules.
+ A perfect example is the plethora of packages in perl4 for dealing
+ with command line options.
+
+ If you are writing a module to expand an already existing set of
+ modules, please coordinate with the author of the package. It
+ helps if you follow the same naming scheme and module interaction
+ scheme as the original author.
+
+ =item Try to design the new module to be easy to extend and reuse.
+
+ Use blessed references. Use the two argument form of bless to bless
+ into the class name given as the first parameter of the constructor,
+ e.g.:
+
+ sub new {
+ my($class) = @_;
+ return bless {}, $class;
+ }
+
+ You might even arrange for your constructors to be called
+ as both static and virtual methods, like this:
+
+ sub new {
+ my($self) = @_;
+ my($class) = ref($self) || $self;
+ return bless {}, $class;
+ }
+
+ Pass arrays as references so more parameters can be added later
+ (it's also faster). Convert functions into methods where
+ appropriate. Split large methods into smaller more flexible ones.
+ Inherit methods from other modules if appropriate.
+
+ Avoid class name tests like: die "Invalid" unless ref $ref eq 'FOO'.
+ Generally you can delete the "eq 'FOO'" part with no harm at all.
+ Let the objects look after themselves! Generally, avoid hardwired
+ class names as far as possible.
+
+ Avoid $r->Class::func() where using @ISA=qw(... Class ...) and
+ $r->func() would work (see perlbot man page for more details).
+
+ Use autosplit so little used or newly added functions won't be a
+ burden to programs which don't use them. Add test functions to
+ the module after __END__ either using AutoSplit or by saying:
+
+ eval join('',<main::DATA>) || die $@ unless caller();
+
+ Does your module pass the 'empty sub-class' test? If you say
+ "@SUBCLASS::ISA = qw(YOURCLASS);" your applications should be able
+ to use SUBCLASS in exactly the same way as YOURCLASS. For example,
+ does your application still work if you change: $obj = new YOURCLASS;
+ into: $obj = new SUBCLASS; ?
+
+ Avoid keeping any state information in your packages. It makes it
+ difficult for multiple other packages to use yours. Keep state
+ information in objects.
+
+ Always use C<-w>. Try to "use strict;" (or "use strict qw(...);").
+ Remember that you can add "no strict qw(...);" to individual blocks
+ of code which need less strictness. Always use C<-w>. Always use C<-w>!
+ Follow the guidelines in the perlstyle(1) manual.
+
+ =item Select what to export.
+
+ Do NOT export method names!
+
+ Do NOT export anything else by default without a good reason!
+
+ Exports pollute the namespace of the module user. If you must
+ export try to use @EXPORT_OK in preference to @EXPORT and avoid
+ short or common names to reduce the risk of name clashes.
+
+ Generally anything not exported is still accessible from outside the
+ module using the ModuleName::item_name (or $blessed_ref->method)
+ syntax. By convention you can use a leading underscore on names to
+ informally indicate that they are 'internal' and not for public use.
+
+ (It is actually possible to get private functions by saying:
+ my $subref = sub { ... }; &$subref; But there's no way to call that
+ directly as a method, since a method must have a name in the symbol
+ table.)
+
+ As a general rule, if the module is trying to be object oriented
+ then export nothing. If it's just a collection of functions then
+ @EXPORT_OK anything but use @EXPORT with caution.
+
+ =item Select a name for the module.
+
+ This name should be as descriptive, accurate and complete as
+ possible. Avoid any risk of ambiguity. Always try to use two or
+ more whole words. Generally the name should reflect what is special
+ about what the module does rather than how it does it. Please use
+ nested module names to informally group or categorise a module.
+ A module should have a very good reason not to have a nested name.
+ Module names should begin with a capital letter.
+
+ Having 57 modules all called Sort will not make life easy for anyone
+ (though having 23 called Sort::Quick is only marginally better :-).
+ Imagine someone trying to install your module alongside many others.
+ If in any doubt ask for suggestions in comp.lang.perl.misc.
+
+ If you are developing a suite of related modules/classes it's good
+ practice to use nested classes with a common prefix as this will
+ avoid namespace clashes. For example: Xyz::Control, Xyz::View,
+ Xyz::Model etc. Use the modules in this list as a naming guide.
+
+ If adding a new module to a set, follow the original author's
+ standards for naming modules and the interface to methods in
+ those modules.
+
+ To be portable each component of a module name should be limited to
+ 11 characters. If it might be used on DOS then try to ensure each is
+ unique in the first 8 characters. Nested modules make this easier.
+
+
+ =item Have you got it right?
+
+ How do you know that you've made the right decisions? Have you
+ picked an interface design that will cause problems later? Have
+ you picked the most appropriate name? Do you have any questions?
+
+ The best way to know for sure, and pick up many helpful suggestions,
+ is to ask someone who knows. Comp.lang.perl.misc is read by just about
+ all the people who develop modules and it's the best place to ask.
+
+ All you need to do is post a short summary of the module, its
+ purpose and interfaces. A few lines on each of the main methods is
+ probably enough. (If you post the whole module it might be ignored
+ by busy people - generally the very people you want to read it!)
+
+ Don't worry about posting if you can't say when the module will be
+ ready - just say so in the message. It might be worth inviting
+ others to help you, they may be able to complete it for you!
+
+
+ =item README and other Additional Files.
+
+ It's well known that software developers usually fully document the
+ software they write. If, however, the world is in urgent need of
+ your software and there is not enough time to write the full
+ documentation please at least provide a README file containing:
+
+ =over
+
+ =item *
+ A description of the module/package/extension etc.
+
+ =item *
+ A copyright notice - see below.
+
+ =item *
+ Prerequisites - what else you may need to have.
+
+ =item *
+ How to build it - possible changes to Makefile.PL etc.
+
+ =item *
+ How to install it.
+
+ =item *
+ Recent changes in this release, especially incompatibilities
+
+ =item *
+ Changes / enhancements you plan to make in the future.
+
+ =back
+
+ If the README file seems to be getting too large you may wish to
+ split out some of the sections into separate files: INSTALL,
+ Copying, ToDo etc.
+
+
+ =item Adding a Copyright Notice.
+
+ How you choose to licence your work is a personal decision.
+ The general mechanism is to assert your Copyright and then make
+ a declaration of how others may copy/use/modify your work.
+
+ Perl, for example, is supplied with two types of licence: The GNU
+ GPL and The Artistic License (see the files README, Copying and
+ Artistic). Larry has good reasons for NOT just using the GNU GPL.
+
+ My personal recommendation, out of respect for Larry, Perl and the
+ perl community at large is to simply state something like:
+
+ =over
+
+ Copyright (c) 1995 Your Name. All rights reserved.
+ This program is free software; you can redistribute it and/or
+ modify it under the same terms as Perl itself.
+
+ =back
+
+ This statement should at least appear in the README file. You may
+ also wish to include it in a Copying file and your source files.
+ Remember to include the other words in addition to the Copyright.
+
+ =item Give the module a version/issue/release number.
+
+ To be fully compatible with the Exporter and MakeMaker modules you
+ should store your module's version number in a non-my package
+ variable called $VERSION and use at least two decimal places
+ (e.g, $VERSION = "0.01"). See Exporter.pm in Perl5.001m or later
+ for details.
+
+ It may be handy to add a function or method to retrieve the number.
+ Use the number in announcements and archive file names when
+ releasing the module (ModuleName-1.02.tar.Z).
+ See perldoc ExtUtils::MakeMaker.pm for details.
+
+
+ =item How to release and distribute a module.
+
+ It's good idea to post an announcement of the availability of your
+ module (or the module itself if small) to the comp.lang.perl.announce
+ Usenet newsgroup. This will at least ensure very wide once-off
+ distribution.
+
+ If possible you should place the module into a major ftp archive and
+ include details of it's location in your announcement.
+
+ Some notes about ftp archives: Please use a long descriptive file
+ name which includes the version number. Most incoming directories
+ will not be readable/listable, i.e., you won't be able to see your
+ file after uploading it. Remember to send your email notification
+ message as soon as possible after uploading else your file may get
+ deleted automatically. Allow time for the file to be processed
+ and/or check the file has been processed before announcing its
+ location.
+
+ FTP Archives for Perl Modules:
+
+ Follow the instructions and links on
+
+ http://franz.ww.tu-berlin.de/modulelist
+
+ or upload to one of these sites:
+
+ ftp://franz.ww.tu-berlin.de/incoming
+ ftp://ftp.cis.ufl.edu/incoming
+
+ and notify upload@franz.ww.tu-berlin.de.
+
+ By using the WWW interface you can ask the Upload Server to mirror
+ your modules from your ftp or WWW site into your own directory on
+ CPAN!
+
+ Please remember to send me an updated entry for the Module list!
+
+
+ =item Take care when changing a released module.
+
+ Always strive to remain compatible with previous released versions
+ (see 2.2 above) Otherwise try to add a mechanism to revert to the
+ old behaviour if people rely on it. Document incompatible changes.
+
+ =back
+
+ =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
+
+ =over 4
+
+ =item There is no requirement to convert anything.
+
+ If it ain't broke, don't fix it! Perl 4 library scripts should
+ continue to work with no problems. You may need to make some minor
+ changes (like escaping non-array @'s in double quoted strings) but
+ there is no need to convert a .pl file into a Module for just that.
+
+
+ =item Consider the implications.
+
+ All the perl applications which make use of the script will need to
+ be changed (slightly) if the script is converted into a module. Is
+ it worth it unless you plan to make other changes at the same time?
+
+
+ =item Make the most of the opportunity.
+
+ If you are going to convert the script to a module you can use the
+ opportunity to redesign the interface. The 'Guidelines for Module
+ Creation' above include many of the issues you should consider.
+
+
+ =item The pl2pm utility will get you started.
+
+ This utility will read *.pl files (given as parameters) and write
+ corresponding *.pm files. The pl2pm utilities does the following:
+
+ =over
+
+ =item *
+ Adds the standard Module prologue lines
+
+ =item *
+ Converts package specifiers from ' to ::
+
+ =item *
+ Converts die(...) to croak(...)
+
+ =item *
+ Several other minor changes
+
+ =back
+
+ Being a mechanical process pl2pm is not bullet proof. The converted
+ code will need careful checking, especially any package statements.
+ Don't delete the original .pl file till the new .pm one works!
+
+
+ =back
+
+
+ =head2 Guidelines for Reusing Application Code
+
+ Complete applications rarely belong in the Perl Module Library.
+
+ Many applications contain some perl code which could be reused.
+ Help save the world! Share your code in a form that makes it easy
+ to reuse.
+
+ Break-out the reusable code into one or more separate module files.
+
+ Take the opportunity to reconsider and redesign the interfaces.
+
+ In some cases the 'application' can then be reduced to a small
+ fragment of code built on top of the reusable modules. In these cases
+ the application could invoked as:
+
+ perl -e 'use Module::Name; method(@ARGV)' ...
+
+ or
+
+ perl -mModule::Name ... (in perl5.002?)
diff -c -r old/pod/perlop.pod new/pod/perlop.pod
*** old/pod/perlop.pod Sat Nov 18 15:24:03 1995
--- new/pod/perlop.pod Sun Dec 10 06:17:46 1995
***************
*** 37,43 ****

In the following sections, these operators are covered in precedence order.

! =head1 DESCRIPTIONS

=head2 Terms and List Operators (Leftward)

--- 37,43 ----

In the following sections, these operators are covered in precedence order.

! =head1 DESCRIPTION

=head2 Terms and List Operators (Leftward)

***************
*** 912,918 ****
data--newlines remain newlines. Unlike in any of the shells, single
quotes do not hide variable names in the command from interpretation.
To pass a $ through to the shell you need to hide it with a backslash.
! The generalized form of backticks is C<qx//>.

Evaluating a filehandle in angle brackets yields the next line from
that file (newline included, so it's never false until end of file, at
--- 912,920 ----
data--newlines remain newlines. Unlike in any of the shells, single
quotes do not hide variable names in the command from interpretation.
To pass a $ through to the shell you need to hide it with a backslash.
! The generalized form of backticks is C<qx//>. (Because backticks
! always undergo shell expansion as well, see L<perlsec> for
! security concerns.)

Evaluating a filehandle in angle brackets yields the next line from
that file (newline included, so it's never false until end of file, at
diff -c -r old/pod/perlpod.pod new/pod/perlpod.pod
*** old/pod/perlpod.pod Sun Nov 19 20:22:59 1995
--- new/pod/perlpod.pod Sun Dec 10 04:05:51 1995
***************
*** 74,80 ****
Note that I'm not at all claiming this to be sufficient for producing a
book. I'm just trying to make an idiot-proof common source for nroff,
TeX, and other markup languages, as used for online documentation.
! Both B<pod2html> and B<pod2man> translators exist.

=head1 Embedding Pods in Perl Modules

--- 74,81 ----
Note that I'm not at all claiming this to be sufficient for producing a
book. I'm just trying to make an idiot-proof common source for nroff,
TeX, and other markup languages, as used for online documentation.
! Translators exist for B<pod2man> (that's for nroff(1) and troff(1)),
! B<pod2html>, B<pod2latex>, and B<pod2fm>.

=head1 Embedding Pods in Perl Modules

***************
*** 83,89 ****
an =cut command. Perl will ignore the pod text. See any of the
supplied library modules for examples.

! =head1 Author

Larry Wall

--- 84,90 ----
an =cut command. Perl will ignore the pod text. See any of the
supplied library modules for examples.

! =head1 AUTHOR

Larry Wall

diff -c -r old/pod/perlre.pod new/pod/perlre.pod
*** old/pod/perlre.pod Sat Dec 9 09:01:01 1995
--- new/pod/perlre.pod Sun Dec 10 03:54:21 1995
***************
*** 4,11 ****

=head1 DESCRIPTION

! For a description of how to use regular expressions in matching
! operations, see C<m//> and C<s///> in L<perlop>. The matching operations can
have various modifiers, some of which relate to the interpretation of
the regular expression inside. These are:

--- 4,14 ----

=head1 DESCRIPTION

! This page describes the syntax of regular expressions in Perl.
! For a description of how to actually use regular expressions in matching
! operations, plus various examples of the same, see C<m//> and C<s///> in L<perlop>.
!
! The matching operations can
have various modifiers, some of which relate to the interpretation of
the regular expression inside. These are:

diff -c -r old/pod/perlrun.pod new/pod/perlrun.pod
*** old/pod/perlrun.pod Wed Feb 22 16:32:59 1995
--- new/pod/perlrun.pod Sun Dec 10 06:09:45 1995
***************
*** 329,336 ****

=item B<-T>

! forces "taint" checks to be turned on. Ordinarily these checks are
! done only when running setuid or setgid. See L<perlsec>.

=item B<-u>

--- 329,338 ----

=item B<-T>

! forces "taint" checks to be turned on so you can test them. Ordinarily these checks are
! done only when running setuid or setgid. It's a good idea to turn
! them on explicitly for programs run on another's behalf, such as CGI
! programs. See L<perlsec>.

=item B<-u>

diff -c -r old/pod/perlsec.pod new/pod/perlsec.pod
*** old/pod/perlsec.pod Wed Feb 22 16:33:02 1995
--- new/pod/perlsec.pod Sun Dec 10 06:21:26 1995
***************
*** 45,51 ****
C<-DSETUID_SCRIPTS_ARE_SECURE_NOW>. The B<Configure> program that builds
Perl tries to figure this out for itself.

! When Perl is executing a setuid script, it takes special precautions to
prevent you from falling into any obvious traps. (In some ways, a Perl
script is more secure than the corresponding C program.) Any command line
argument, environment variable, or input is marked as "tainted", and may
--- 45,52 ----
C<-DSETUID_SCRIPTS_ARE_SECURE_NOW>. The B<Configure> program that builds
Perl tries to figure this out for itself.

! When executing a setuid script, or when you have turned on taint checking
! explicitly using the B<-T> flag, Perl takes special precautions to
prevent you from falling into any obvious traps. (In some ways, a Perl
script is more secure than the corresponding C program.) Any command line
argument, environment variable, or input is marked as "tainted", and may
***************
*** 123,125 ****
--- 124,147 ----
so be careful what you print out. The tainting mechanism is intended to
prevent stupid mistakes, not to remove the need for thought.

+ This gives us a reasonably safe way to open a file or pipe: just reset the
+ id set to the original IDs. Here's a way to do backticks reasonably
+ safely. Notice how the exec() is not called with a string that the shell
+ could expand. By the time we get to the exec(), tainting is turned off,
+ however, so be careful what you call and what you pass it.
+
+ die unless defined $pid = open(KID, "-|");
+ if ($pid) { # parent
+ while (<KID>) {
+ # do something
+ }
+ close KID;
+ } else {
+ $> = $<;
+ $) = $(; # BUG: initgroups() not called
+ exec 'program', 'arg1', 'arg2';
+ die "can't exec program: $!";
+ }
+
+ For those even more concerned about safety, see the I<Safe> and I<Safe CGI>
+ modules at a CPAN site near you. See L<perlmod> for a list of CPAN sites.
diff -c -r old/pod/perlstyle.pod new/pod/perlstyle.pod
*** old/pod/perlstyle.pod Tue Oct 18 10:40:13 1994
--- new/pod/perlstyle.pod Sun Dec 10 06:33:45 1995
***************
*** 4,15 ****

=head1 DESCRIPTION

- =head2 Style
-
Each programmer will, of course, have his or her own preferences in
regards to formatting, but there are some general guidelines that will
make your programs easier to read, understand, and maintain.

Regarding aesthetics of code lay out, about the only thing Larry
cares strongly about is that the closing curly brace of
a multi-line BLOCK should line up with the keyword that started the construct.
--- 4,20 ----

=head1 DESCRIPTION

Each programmer will, of course, have his or her own preferences in
regards to formatting, but there are some general guidelines that will
make your programs easier to read, understand, and maintain.

+ The most important thing is to run your programs under the B<-w>
+ flag at all times. You may turn it off explicitly for particular
+ portions of code via the C<$^W> variable if you must. You should
+ also always run under C<use strict> or know the reason why not.
+ The <use sigtrap> and even <use diagnostics> pragmas may also prove
+ useful.
+
Regarding aesthetics of code lay out, about the only thing Larry
cares strongly about is that the closing curly brace of
a multi-line BLOCK should line up with the keyword that started the construct.
***************
*** 166,171 ****
--- 171,193 ----
Choose mnemonic identifiers. If you can't remember what mnemonic means,
you've got a problem.

+ =item *
+
+ Be consistent in your variable naming conventions. One system uses
+ case to give reminders about the intended scope of a variable. For
+ example, $ALL_CAPS_HERE for (virtual) constants, $Some_Caps_Here for
+ package-wide global/static, and $no_caps_here for purely my() variables.
+
+ =item *
+
+ While short identifiers like $gotit are probably ok, don't write longer
+ multiword identifiers without underscores. Things like
+ $NoUnderBarsInThisVar are very difficult to read, especially for
+ non-native speakers. Just use $Under_Bars_In_This_Var instead; it makes
+ them longer but that's not a problem if you're using a decent
+ editor--except in package (module) names where filename length constraints on
+ impoverished computers without operating systems can prove problematic.
+
=item *

If you have a really hairy regular expression, use the C</x> modifier and
***************
*** 222,225 ****
Be nice.

=back
-
--- 244,246 ----
diff -c -r old/pod/perltrap.pod new/pod/perltrap.pod
*** old/pod/perltrap.pod Wed Nov 15 19:36:11 1995
--- new/pod/perltrap.pod Sun Dec 10 07:05:29 1995
***************
*** 4,17 ****

=head1 DESCRIPTION

! The biggest trap of all is forgetting to use the B<-w> switch;
! see L<perlrun>. Making your entire program runnable under

- use strict;
-
- can help make your program more bullet-proof, but sometimes
- it's too annoying for quick throw-away programs.
-
=head2 Awk Traps

Accustomed B<awk> users should take special note of the following:
--- 4,13 ----

=head1 DESCRIPTION

! The biggest trap of all is forgetting to use the B<-w> switch; see
! L<perlrun>. The second biggest trap is not making your entire program
! runnable under C<use strict>.

=head2 Awk Traps

Accustomed B<awk> users should take special note of the following:
***************
*** 358,363 ****
--- 354,367 ----

Symbols starting with C<_> are no longer forced into package C<main>, except
for $_ itself (and @_, etc.).
+
+ =item *
+
+ Double-colon is now a valid package separator in an identifier. Thus these
+ behave differently in perl4 vs. perl5:
+
+ print "$a::$b::$c\n";
+ print "$var::abc::xyz\n";

=item *

diff -c -r old/pod/perlvar.pod new/pod/perlvar.pod
*** old/pod/perlvar.pod Wed Nov 15 19:36:59 1995
--- new/pod/perlvar.pod Sun Dec 10 06:12:49 1995
***************
*** 444,450 ****

Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can only be set on machines
that support the corresponding I<set[re][ug]id()> routine. "C<$(>" and "C<$)>"
! can only be swapped on machines supporting setregid().

=item $PROGRAM_NAME

--- 444,452 ----

Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can only be set on machines
that support the corresponding I<set[re][ug]id()> routine. "C<$(>" and "C<$)>"
! can only be swapped on machines supporting setregid(). Because Perl doesn't
! currently use initgroups(), you can't set your group vector to multiple groups.
!

=item $PROGRAM_NAME

diff -c -r old/pod/perlxstut.pod new/pod/perlxstut.pod
*** old/pod/perlxstut.pod Mon Nov 20 11:02:12 1995
--- new/pod/perlxstut.pod Sat Dec 9 12:54:48 1995
***************
*** 22,28 ****
Our first extension will be very simple. When we call the routine in the
extension, it will print out a well-known message and terminate.

! Run "h2xs -A -n Test1". This creates a directory named Test1, possibly under
ext/ if it exists in the current working directory. Four files will be
created in the Test1 dir: MANIFEST, Makefile.PL, Test1.pm, Test1.xs.

--- 22,28 ----
Our first extension will be very simple. When we call the routine in the
extension, it will print out a well-known message and terminate.

! Run C<h2xs -A -n Test1>. This creates a directory named Test1, possibly under
ext/ if it exists in the current working directory. Four files will be
created in the Test1 dir: MANIFEST, Makefile.PL, Test1.pm, Test1.xs.

***************
*** 80,86 ****
CODE:
printf("Hello, world!\n");

! Now we'll run "perl Makefile.PL". This will create a real Makefile,
which make needs. It's output looks something like:

% perl Makefile.PL
--- 80,86 ----
CODE:
printf("Hello, world!\n");

! Now we'll run C<perl Makefile.PL>. This will create a real Makefile,
which make needs. It's output looks something like:

% perl Makefile.PL
***************
*** 128,134 ****
Now let's create a simple extension that will take a single argument and
return 0 if the argument is even, 1 if the argument is odd.

! Run "h2xs -A -n Test2". This will create a Test2 directory with a file
Test2.xs underneath it. Add the following to the end of the XS file:

int
--- 128,134 ----
Now let's create a simple extension that will take a single argument and
return 0 if the argument is even, 1 if the argument is odd.

! Run C<h2xs -A -n Test2>. This will create a Test2 directory with a file
Test2.xs underneath it. Add the following to the end of the XS file:

int
***************
*** 236,242 ****
Our third extension will take one argument as its input, round off that
value, and set the argument to the rounded value.

! Run "h2xs -A -n Test3". This will create a Test3 directory with a file
Test3.xs underneath it. Add the following to the end of the XS file:

void
--- 236,242 ----
Our third extension will take one argument as its input, round off that
value, and set the argument to the rounded value.

! Run C<h2xs -A -n Test3>. This will create a Test3 directory with a file
Test3.xs underneath it. Add the following to the end of the XS file:

void
***************
*** 438,446 ****
Okay, now that we have a header file and a library, let's begin actually
writing the extension.

! Run "h2xs -n Test4 /tmp/test4/include/libtest4.h" (notice we are no longer
! specifying -A as an argument). This will create a Test4 directory with a file
! Test4.xs underneath it. If we look at it now, we'll see some interesting
things have been added to the various files.

=over 2
--- 438,446 ----
Okay, now that we have a header file and a library, let's begin actually
writing the extension.

! Run C<h2xs -n Test4 /tmp/test4/include/libtest4.h> (notice we are no longer
! specifying B<-A> as an argument). This will create a Test4 directory with a file
! F<Test4.xs> underneath it. If we look at it now, we'll see some interesting
things have been added to the various files.

=over 2
diff -c -r old/pod/pod2man new/pod/pod2man
*** old/pod/pod2man Sat Dec 9 09:35:40 1995
--- new/pod/pod2man Sun Dec 10 07:10:19 1995
***************
*** 1,35 ****
- eval 'exec perl -S $0 "$@"'
- if 0;

$/ = "";
$cutting = 1;

! $CFont = 'CW';
! if ($ARGV[0] =~ s/-fc(.*)//) {
! shift;
! $CFont = $1 || shift;
}

if (length($CFont) == 2) {
$CFont_embed = "\\f($CFont";
! }
elsif (length($CFont) == 1) {
$CFont_embed = "\\f$CFont";
! }
else {
! die "Roff font should be 1 or 2 chars, not `$CFont_embed'";
! }

! $name = @ARGV ? $ARGV[0] : "something";
$name =~ s/\..*//;

print <<"END";
.rn '' }`
''' \$RCSfile\$\$Revision\$\$Date\$
! '''
''' \$Log\$
! '''
.de Sh
.br
.if t .Sp
--- 1,388 ----

+ eval 'exec perl -S $0 "$@"'
+ if 0;
+
+ =head1 NAME
+
+ pod2man - translate embedded Perl pod directives into man pages
+
+ =head1 SYNOPSIS
+
+ B<pod2man>
+ [ B<--section=>I<manext> ]
+ [ B<--release=>I<relpatch> ]
+ [ B<--center=>I<string> ]
+ [ B<--date=>I<string> ]
+ [ B<--fixed=>I<font> ]
+ [ B<--official> ]
+ I<inputfile>
+
+ =head1 DESCRIPTION
+
+ B<pod2man> converts its input file containing embedded pod directives (see
+ L<perlpod>) into nroff source suitable for viewing with nroff(1) or
+ troff(1) using the man(7) macro set.
+
+ Besides the obvious pod conversions, B<pod2man> also takes are of func(),
+ func(n), and simple variable references like $foo or @bar so you don't
+ have to use code escapes for them; complex expressions like C<$fred{'stuff'}> will
+ still need to be escaped, though. Other nagging little roffish things
+ that it catches include translating the minus in something like foo-bar,
+ making a long dash--like this--into a real em dash, fixing up "paired
+ quotes", putting a little space after the parens in something like func(),
+ making C++ and PI look right, making double underbars have a little tiny
+ space between them, making ALLCAPS a teeny bit smaller in troff(1), and
+ escaping backslashes so you don't have to.
+
+ =head1 OPTIONS
+
+ =over 8
+
+ =item center
+
+ Set the centered header to a specific string. The default is
+ "User Contributed Perl Documentation", unless the C<--official> flag is
+ given, in which case the default is "Perl Programmers Reference Guide".
+
+ =item date
+
+ Set the left-hand footer string to this value. By default,
+ the modification date of the input file will be used.
+
+ =item fixed
+
+ The fixed font to use for code refs. Defaults to CW.
+
+ =item official
+
+ Set the default header to indicate that this page is of
+ the standard release in case C<--center> is not given.
+
+ =item release
+
+ Set the centered footer. By default, this is the current
+ perl release.
+
+ =item section
+
+ Set the section for the C<.TH> macro. The standard conventions on
+ sections are to use 1 for user commands, 2 for system calls, 3 for
+ functions, 4 for devices, 5 for file formats, 6 for games, 7 for
+ miscellaneous information, and 8 for administrator commands. This works
+ best if you put your Perl man pages in a separate tree, like
+ F</usr/local/perl/man/>. By default, section 1 will be used
+ unless the file ends in F<.pm> in which case section 3 will be selected.
+
+ =back
+
+ =head1 Anatomy of a Proper Man Page
+
+ For those not sure of the proper layout of a man page, here's
+ an example of the skeleton of a proper man page. Head of the
+ major headers should be setout as a C<=head1> directive, and
+ are historically written in the rather startling ALL UPPER CASE
+ format, although this is not mandatory.
+ Minor headers may be included using C<=head2>, and are
+ typically in mixed case.
+
+ =over 10
+
+ =item NAME
+
+ Mandatory section; should be a comma-separated list of programs or
+ functions documented by this podpage, such as:
+
+ foo, bar - programs to do something
+
+ =item SYNOPSIS
+
+ A short usage summary for programs and functions, which
+ may someday be deemed mandatory.
+
+ =item DESCRIPTION
+
+ Long drawn out discussion of the program. It's a good idea to break this
+ up into subsections using the C<=head2> directives, like
+
+ =head2 A Sample Subection
+
+ =head2 Yet Another Sample Subection
+
+ =item OPTIONS
+
+ Some people make this separate from the description.
+
+ =item RETURN VALUE
+
+ What the program or function returns if successful.
+
+ =item ERRORS
+
+ Exceptions, teturn codes, exit stati, and errno settings.
+
+ =item EXAMPLES
+
+ Give some example uses of the program.
+
+ =item ENVIRONMENT
+
+ Envariables this program might care about.
+
+ =item FILES
+
+ All files used by the program. You should probably use the FE<lt>E<gt>
+ for these.
+
+ =item SEE ALSO
+
+ Other man pages to check out, like man(1), man(7), makewhatis(8), or catman(8).
+
+ =item NOTES
+
+ Miscellaneous commentary.
+
+ =item CAVEATS
+
+ Things to take special care with; sometimes called WARNINGS.
+
+ =item DIAGNOSTICS
+
+ All possible messages the program can print out--and
+ what they mean.
+
+ =item BUGS
+
+ Things that are broken or just don't work quite right.
+
+ =item RESTRICTIONS
+
+ Bugs you don't plan to fix :-)
+
+ =item AUTHOR
+
+ Who wrote it (or AUTHORS if multiple).
+
+ =item HISTORY
+
+ Programs derived from other sources sometimes have this, or
+ you might keep a modification long here.
+
+ =back
+
+ =head1 EXAMPLES
+
+ pod2man program > program.1
+ pod2man some_module.pm > /usr/perl/man/man3/some_module.3
+ pod2man --section=7 note.pod > note.7
+
+ =head1 DIAGNOSTICS
+
+ The following diagnostics are generated by B<pod2man>. Items
+ marked "(W)" are non-fatal, whereas the "(F)" errors will cause
+ B<pod2man> to immediately exit with a non-zero status.
+
+ =over 4
+
+ =item bad option in paragraph %d of %s: ``%s'' should be [%s]<%s>
+
+ (W) If you start include an option, you should set it off
+ as bold, italic, or code.
+
+ =item can't open %s: %s
+
+ (F) The input file wasn't available for the given reason.
+
+ =item high bit char in input stream
+
+ (W) You can't use high-bit characters in the input stream,
+ because the translator uses them for its own nefarious purposes.
+ Use an HTML entity in angle brackets instead.
+
+ =item Improper man page - no dash in NAME header in paragraph %d of %s
+
+ (W) The NAME header did not have an isolated dash in it. This is
+ considered important.
+
+ =item Invalid man page - no NAME line in %s
+
+ (F) You did not include a NAME header, which is essential.
+
+ =item roff font should be 1 or 2 chars, not `%s' (F)
+
+ (F) The font specified with the C<--fixed> option was not
+ a one- or two-digit roff font.
+
+ =item %s is missing required section: %s
+
+ (W) Required sections include NAME, DESCRIPTION, and if you're
+ using a section starting with a 3, also a SYNOPSIS. Actually,
+ not having a NAME is a fatal.
+
+ =item Unknown escape: %s in %s
+
+ (W) An unknown HTML entity (probably for an 8-bit character) was given via
+ a C<E<lt>E<gt>> directive. Besides amp, lt, gt, and quot, recognized
+ entities are Aacute, aacute, Acirc, acirc, AElig, aelig, Agrave, agrave,
+ Aring, aring, Atilde, atilde, Auml, auml, Ccedil, ccedil, Eacute, eacute,
+ Ecirc, ecirc, Egrave, egrave, ETH, eth, Euml, euml, Iacute, iacute, Icirc,
+ icirc, Igrave, igrave, Iuml, iuml, Ntilde, ntilde, Oacute, oacute, Ocirc,
+ ocirc, Ograve, ograve, Oslash, oslash, Otilde, otilde, Ouml, ouml, szlig,
+ THORN, thorn, Uacute, uacute, Ucirc, ucirc, Ugrave, ugrave, Uuml, uuml,
+ Yacute, yacute, and yuml.
+
+ =item Unmatched =back
+
+ (W) You have a C<=back> without a corresponding C<=over>.
+
+ =item Unrecognized pod directive: %s
+
+ (W) You specified a pod directive that isn't in the known list of
+ C<=head1>, C<=head2>, C<=item>, C<=over>, C<=back>, or C<=cut>.
+
+
+ =back
+
+ =head1 NOTES
+
+ If you would like to print out a lot of man page continuously, you
+ probably want to set the C and D registers to set contiguous page
+ numbering and even/odd paging, at least one some versions of man(7).
+ Settting the F register will get you some additional experimental
+ indexing:
+
+ troff -man -rC1 -rD1 -rF1 perl.1 perldata.1 perlsyn.1 ...
+
+ The indexing merely outputs messages via C<.tm> for each
+ major page, section, subsection, item, and any C<XE<lt>E<gt>>
+ directives.
+
+
+ =head1 RESTRICTIONS
+
+ You shouldn't use 8-bit characters in the input stream, as these
+ will be used by the translator.
+
+ =head1 BUGS
+
+ The =over and =back directives don't really work right. They
+ take absolute positions instead of offsets, don't nest well, and
+ making people count is suboptimal in any event.
+
+ =head1 AUTHORS
+
+ Original prototype by Larry Wall, but so massively hacked over by
+ Tom Christiansen such that Larry probably doesn't recognize it anymore.
+
+ =cut
+
$/ = "";
$cutting = 1;

! ($version,$patch) = `\PATH=.:..:\$PATH; perl -v` =~ /version (\d\.\d{3}(?: +)(?:\S+)?)(?:.*patchlevel (\d\S*))?/s;
! $DEF_RELEASE = "perl $version";
! $DEF_RELEASE .= ", patch $patch" if $patch;
!
!
! sub makedate {
! my $secs = shift;
! my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime($secs);
! my $mname = (qw{Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec})[$mon];
! return "$mday/$mname/$year";
}

+ use Getopt::Long;
+
+ $DEF_SECTION = 1;
+ $DEF_CENTER = "User Contributed Perl Documentation";
+ $STD_CENTER = "Perl Programmers Reference Guide";
+ $DEF_FIXED = 'CW';
+
+ sub usage {
+ warn "$0: @_\n" if @_;
+ die <<EOF;
+ usage: $0 [options] podpage
+ Options are:
+ --section=manext (default "$DEF_SECTION")
+ --release=relpatch (default "$DEF_RELEASE")
+ --center=string (default "$DEF_CENTER")
+ --date=string (default "$DEF_DATE")
+ --fixed=font (default "$DEF_FIXED")
+ --official (default NOT)
+ EOF
+ }
+
+ $uok = GetOptions( qw(
+ section=s
+ release=s
+ center=s
+ date=s
+ fixed=s
+ official
+ help));
+
+ $DEF_DATE = makedate((stat($ARGV[0]))[9] || time());
+
+ usage("Usage error!") unless $uok;
+ usage() if $opt_help;
+ usage("Need one and only one podpage argument") unless @ARGV == 1;
+
+ $section = $opt_section || ($ARGV[0] =~ /\.pm$/ ? 3 : $DEF_SECTION);
+ $RP = $opt_release || $DEF_RELEASE;
+ $center = $opt_center || ($opt_official ? $STD_CENTER : $DEF_CENTER);
+
+ $CFont = $opt_fixed || $DEF_FIXED;
+
if (length($CFont) == 2) {
$CFont_embed = "\\f($CFont";
! }
elsif (length($CFont) == 1) {
$CFont_embed = "\\f$CFont";
! }
else {
! die "roff font should be 1 or 2 chars, not `$CFont_embed'";
! }

! $section = $opt_section || $DEF_SECTION;
! $date = $opt_date || $DEF_DATE;
!
! for (qw{NAME DESCRIPTION}) {
! # for (qw{NAME DESCRIPTION AUTHOR}) {
! $wanna_see{$_}++;
! }
! $wanna_see{SYNOPSIS}++ if $section =~ /^3/;
!
!
! $name = @ARGV ? $ARGV[0] : "<STDIN>";
! $Filename = $name;
! $name = uc($name) if $section =~ /^1/;
$name =~ s/\..*//;

+ if ($name ne 'something') {
+ FCHECK: {
+ open(F, "< $ARGV[0]") || die "can't open $ARGV[0]: $!";
+ while (<F>) {
+ if (/^=head1\s+NAME\s*$/m) { # the silly /m is due to SelfLoader
+ $_ = <F>;
+ unless (/\s*-+\s+/) {
+ $oops++;
+ warn "$0: Improper man page - no dash in NAME header in paragraph $. of $ARGV[0]:\n"
+ }
+ %namedesc = split /\s+-\s+/;
+ last FCHECK;
+ }
+ }
+ die "$0: Invalid man page - no NAME line in $ARGV[0]\n";
+ }
+ close F;
+ }
+
print <<"END";
.rn '' }`
''' \$RCSfile\$\$Revision\$\$Date\$
! '''
''' \$Log\$
! '''
.de Sh
.br
.if t .Sp
***************
*** 36,41 ****
--- 389,395 ----
.ne 5
.PP
\\fB\\\\\$1\\fR
+ .Px Subsection "\\\\\$1"
.PP
..
.de Sp
***************
*** 67,72 ****
--- 421,427 ----
.tr \\(*W-|\\(bv\\*(Tr
.ie n \\{\\
.ds -- \\(*W-
+ .ds PI pi
.if (\\n(.H=4u)&(1m=24u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-12u'-\\" diablo 10 pitch
.if (\\n(.H=4u)&(1m=20u) .ds -- \\(*W\\h'-12u'\\(*W\\h'-8u'-\\" diablo 12 pitch
.ds L" ""
***************
*** 81,95 ****
.ds R" ''
.ds L' `
.ds R' '
! .if t .ds PI \\(*p
! .if n .ds PI PI
'br\\}
! .TH \U$name\E 1 "\\*(RP"
.UC
END

print <<'END';
! .if n .hy 0
.if n .na
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ \" put $1 in typewriter font
--- 436,475 ----
.ds R" ''
.ds L' `
.ds R' '
! .ds PI \\(*p
'br\\}
! END
!
! print <<'END';
! .if \nF \{
! .de Px
! .tm Index:\\$1\t\\n%\t"\\$2"
! ..
! .am SH
! .Px Header "\\$1"
! ..
! .am IP
! .Px Item "\\$1"
! ..
! .nr % 0
! .rr F
! .\}
! ..
! END
!
! print <<"END";
! .TH $name $section "$RP" "$date" "$center"
! .Px Title "$name $section"
.UC
END

+ while (($name, $desc) = each %namedesc) {
+ for ($name, $desc) { s/^\s+//; s/\s+$//; }
+ print qq(.Px Name "$name - $desc"\n);
+ }
+
print <<'END';
! .if n .hy 0
.if n .na
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ \" put $1 in typewriter font
***************
*** 130,137 ****
. ds ~ ~
. ds ? ?
. ds ! !
! . ds /
! . ds q
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
--- 510,517 ----
. ds ~ ~
. ds ? ?
. ds ! !
! . ds /
! . ds q
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
***************
*** 224,230 ****
# trofficate backslashes; must do it before what happens below
s/\\/noremap('\\e')/ge;

# intuit something and get it wrong due to fmting

s/([A-Z]<[^<>]*>)/noremap($1)/ge;
--- 604,610 ----
# trofficate backslashes; must do it before what happens below
s/\\/noremap('\\e')/ge;

# intuit something and get it wrong due to fmting

s/([A-Z]<[^<>]*>)/noremap($1)/ge;
***************
*** 258,271 ****
[^\051]*?
\)
)
! }x && $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/)
{
! warn "``$1'' should be a [LCI]<$1> ref";
! }

while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) {
! warn "``$1'' should be [CB]<$1> ref";
! }

# put it back so we get the <> processed again;
clear_noremap(0); # 0 means leave the E's
--- 638,653 ----
[^\051]*?
\)
)
! }x && $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/)
{
! warn "$0: bad option in paragraph $. of $ARGV: ``$1'' should be [LCI]<$1>\n";
! $oops++;
! }

while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) {
! warn "$0: bad option in paragraph $. of $ARGV: ``$1'' should be [CB]<$1>\n";
! $oops++;
! }

# put it back so we get the <> processed again;
clear_noremap(0); # 0 means leave the E's
***************
*** 274,280 ****
# trofficate backslashes
s/\\/noremap('\\e')/ge;

! }

# need to hide E<> first; they're processed in clear_noremap
s/(E<[^<>]+>)/noremap($1)/ge;
--- 656,662 ----
# trofficate backslashes
s/\\/noremap('\\e')/ge;

! }

# need to hide E<> first; they're processed in clear_noremap
s/(E<[^<>]+>)/noremap($1)/ge;
***************
*** 292,298 ****
# no break -- usually we want C<> for this
s/S<([^<>]*)>/nobreak($1)/eg;

s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the I<$1>$2 manpage:g;

# LREF: an =item on another manpage
--- 674,680 ----
# no break -- usually we want C<> for this
s/S<([^<>]*)>/nobreak($1)/eg;

s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the I<$1>$2 manpage:g;

# LREF: an =item on another manpage
***************
*** 326,332 ****
s{
L<
(?:
! ([a-zA-Z]\S+?) /
)?
"?(.*?)"?
>
--- 708,714 ----
s{
L<
(?:
! ([a-zA-Z]\S+?) /
)?
"?(.*?)"?
>
***************
*** 335,341 ****
$1 # if no $1, assume it means on this page.
? "the section on I<$2> in the I<$1> manpage"
: "the section on I<$2>"
! }
}gex;

s/Z<>/\\&/g;
--- 717,723 ----
$1 # if no $1, assume it means on this page.
? "the section on I<$2> in the I<$1> manpage"
: "the section on I<$2>"
! }
}gex;

s/Z<>/\\&/g;
***************
*** 362,367 ****
--- 744,751 ----
$cutting = 1;
}
elsif ($Cmd eq 'head1') {
+ s/\s+$//;
+ delete $wanna_see{$_} if exists $wanna_see{$_};
print qq{.SH "$_"\n}
}
elsif ($Cmd eq 'head2') {
***************
*** 381,387 ****
print STDOUT qq{.Ip "$_" $indent\n};
}
else {
! warn "Unrecognized directive: $Cmd\n";
}
}
else {
--- 765,771 ----
print STDOUT qq{.Ip "$_" $indent\n};
}
else {
! warn "Unrecognized pod directive: $Cmd\n";
}
}
else {
***************
*** 400,405 ****
--- 784,800 ----
.rn }` ''
END

+ if (%wanna_see) {
+ @missing = keys %wanna_see;
+ warn "$0: $Filename is missing required section"
+ . (@missing > 1 && "s")
+ . ": @missing\n";
+ $oops++;
+ }
+
+ exit;
+ #exit ($oops != 0);
+
#########################################################################

sub nobreak {
***************
*** 410,415 ****
--- 805,812 ----

sub escapes {

+ s/X<(.*?)>/mkindex($1)/ge;
+
# translate the minus in foo-bar into foo\-bar for roff
s/([^0-9a-z-])-([^-])/$1\\-$2/g;

***************
*** 426,433 ****

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
#s/(?:(?!")(?:.)--(?:"))|(?:(?:")--(?!")(?:.))/\\*(--/g;
-

# make sure that func() keeps a bit a space tween the parens
### s/\b\(\)/\\|()/g;
### s/\b\(\)/(\\|)/g;
--- 823,830 ----

#s/(?!")(?:.)--(?!")(?:.)/\\*(--/g;
#s/(?:(?!")(?:.)--(?:"))|(?:(?:")--(?!")(?:.))/\\*(--/g;

+
# make sure that func() keeps a bit a space tween the parens
### s/\b\(\)/\\|()/g;
### s/\b\(\)/(\\|)/g;
***************
*** 438,444 ****
# make double underbars have a little tiny space between them
s/__/_\\|_/g;

s/\bPI\b/noremap('\\*(PI')/ge;

# make all caps a teeny bit smaller, but don't muck with embedded code literals
--- 835,841 ----
# make double underbars have a little tiny space between them
s/__/_\\|_/g;

s/\bPI\b/noremap('\\*(PI')/ge;

# make all caps a teeny bit smaller, but don't muck with embedded code literals
***************
*** 461,467 ****
(
\b[A-Z]{2,}[\/A-Z+:\-\d_\$]*\b
)
! } {
$1 . noremap( '\\s-1' . $2 . '\\s0' )
}egmox;

--- 858,864 ----
(
\b[A-Z]{2,}[\/A-Z+:\-\d_\$]*\b
)
! } {
$1 . noremap( '\\s-1' . $2 . '\\s0' )
}egmox;

***************
*** 477,485 ****
# what about $" ?
} else {
noremap(qq{${CFont_embed}$_\\fR});
! }
noremap(qq{.CQ "$_" \n\\&});
! }

sub makespace {
if ($indent) {
--- 874,882 ----
# what about $" ?
} else {
noremap(qq{${CFont_embed}$_\\fR});
! }
noremap(qq{.CQ "$_" \n\\&});
! }

sub makespace {
if ($indent) {
***************
*** 490,511 ****
}
}

sub font {
local($font) = shift;
return '\\f' . noremap($font);
! }

sub noremap {
local($thing_to_hide) = shift;
$thing_to_hide =~ tr/\000-\177/\200-\377/;
return $thing_to_hide;
! }

sub init_noremap {
if ( /[\200-\377]/ ) {
! warn "hit bit char in input stream";
! }
! }

sub clear_noremap {
my $ready_to_print = $_[0];
--- 887,919 ----
}
}

+ sub mkindex {
+ my ($entry) = @_;
+ my @entries = split m:\s*/\s*:, $entry;
+ print ".Px Xref ";
+ for $entry (@entries) {
+ print qq("$entry" );
+ }
+ print "\n";
+ return '';
+ }
+
sub font {
local($font) = shift;
return '\\f' . noremap($font);
! }

sub noremap {
local($thing_to_hide) = shift;
$thing_to_hide =~ tr/\000-\177/\200-\377/;
return $thing_to_hide;
! }

sub init_noremap {
if ( /[\200-\377]/ ) {
! warn "high bit char in input stream";
! }
! }

sub clear_noremap {
my $ready_to_print = $_[0];
***************
*** 522,528 ****
E<
( [A-Za-z]+ )
>
! } {
do {
exists $HTML_Escapes{$1}
? do { $HTML_Escapes{$1} }
--- 930,936 ----
E<
( [A-Za-z]+ )
>
! } {
do {
exists $HTML_Escapes{$1}
? do { $HTML_Escapes{$1} }
***************
*** 529,538 ****
: do {
warn "Unknown escape: $& in $_";
"E<$1>";
! }
! }
}egx if $ready_to_print;
! }

sub internal_lrefs {
local($_) = shift;
--- 937,946 ----
: do {
warn "Unknown escape: $& in $_";
"E<$1>";
! }
! }
}egx if $ready_to_print;
! }

sub internal_lrefs {
local($_) = shift;
***************
*** 545,551 ****
$retstr .= "C<$items[$i]>";
$retstr .= ", " if @items > 2 && $i != $#items;
$retstr .= " and " if $i+2 == @items;
! }

$retstr .= " entr" . ( @items > 1 ? "ies" : "y" )
. " elsewhere in this document";
--- 953,959 ----
$retstr .= "C<$items[$i]>";
$retstr .= ", " if @items > 2 && $i != $#items;
$retstr .= " and " if $i+2 == @items;
! }

$retstr .= " entr" . ( @items > 1 ? "ies" : "y" )
. " elsewhere in this document";
***************
*** 552,558 ****

return $retstr;

! }

BEGIN {
%HTML_Escapes = (
--- 960,966 ----

return $retstr;

! }

BEGIN {
%HTML_Escapes = (
***************
*** 625,627 ****
--- 1033,1036 ----
"yuml" => "y\\*:", # small y, dieresis or umlaut mark
);
}
+