http://qs1969.pair.com?node_id=147236

emcb has asked for the wisdom of the Perl Monks concerning the following question:

Im quite new to perl and i have just attempted to write my first perl mod. To me it looks ok, but im still learning so it's probabley not. I have run into a problem with the POD. This is the error i get from pod2html:

% pod2html ./General.pm > General.html D:\perl\perl5.6.1.628\bin/pod2html.bat: no title for ./General.pm at D +:/perl/perl5.6.1.628/lib/Pod/Html.pm line 402

There's probenle more stuff im doing wrong:

###################################################################### +###################### # Name the package. package ExNet::General; # Append to the @INC array. use lib qw( @INC H:/SITES/emcb/lib/perl5 ); # Load other needed modules. #use Archive::Tar; #use Cwd; use Digest::MD5 qw( md5 ); use strict; use warnings; # Setup the OO interface #our $tar = Archive::Tar->new(); # Require the Exporter. require Exporter; # Set @ISA and the subs loaded by default. our @ISA = qw( Exporter ); our @EXPORT_OK = qw( printNav returnRef getURLS_File returnPasswd er +rorDie errorWarn ); our $VERSION = '0.1a'; # Need to add these functions: OpenLog CreateLog FlushLog; # OpenLog: Open a log for writing. # CreateLog: Create a new log. # FlushLog: Empty the log and tar' it up. # General module for ExNet trivial functions like returning a MD5 # sum of a string, Creating new logs, Flushing logs to an archive # and so on... Just general stuff. # PRIVATE_ENV: # This environment hash is private to this package, and only # methods belonging to this package can access it. our %PRIVATE_ENV = ( 'EXNET_SERVER_ROOT' => 'H:/SITES/emcb', 'EXNET_DOCUMENT_ROOT' => 'sites/exnet.emcb.co. +uk/public_html', 'EXNET_CGI_ROOT' => 'sites/exnet.emcb.co. +uk/cgi-local', 'EXNET_CGI_ENGINE' => 'sites/exnet.emcb.co. +uk/cgi-local/exnet.pl', 'EXNET_LOG_ROOT' => 'sites/exnet.emcb.co. +uk', 'EXNET_ERRORLOG_NAME' => 'exnet.general.error_ +log', ); # GLOBAL_ENV: # This environment is public and can be accessed via a referrence. our %GLOBAL_ENV = ( 'EXNET_SERVER_NAME' => 'EMCBi ExtraNet Se +rver', 'EXNET_URLS_FILE' => 'sites/exnet.emcb. +co.uk/urls.txt', 'EXNET_HTTP_HEADER' => 'text/html', 'EXNET_FONT_FAMILY' => 'Verdana,Arial,Hel +vetica,Geneva', 'EXNET_TEXT_COLOUR' => '#000000', 'EXNET_NLINK_COLOUR' => '#000099', 'EXNET_HLINK_COLOUR' => '#0066FF', ); # Setup the local referrences to the PRIVATE/GLOBAL_ENV hashes. # Parse the @urls and @titles in referrences. our $PENV = \%PRIVATE_ENV; our $GENV = \%GLOBAL_ENV; # ------------------------------------------------------------------ +---------------------- # # Begin Exported Methods + # # ------------------------------------------------------------------ +---------------------- # #->new # ExNet::General constructor sub new { my $class = shift; my $self = {}; my %OPTIONS = @ARG; bless( $self, $class ); return $self; } #->returnRef # ExNet::General hash-referrence returner sub returnRef { my $packname = $_[0]; if( !$packname ) { return 0; } if( $packname == "GLOBAL" ) { return $ExNet::General::GENV; } else { return 0; } } #->getURLS_File # ExNet::General Parse the URLS file sub getURLS_File { my( $names,$links ) = @_; if( $names==0 || "" or $links==0 || "" ) { errorDie("You did not specify a referrence to the names/links ar +ray. See \'perldoc ExNet::General\' for help.<br>\n"); } else { my $HOME = $PENV->{'EXNET_SERVER_ROOT'},"/"; open( URLSFILE, $PENV->{'EXNET_URLS_FILE'} ) || errorDie("Could +not open the URLS_File: $!<br>\n"; my $line = 0; my( $title,$url,@titles,@urls ); URLS: while( <URLSFILE> ) { next URLS if /^#/; ( $title,$url ) = split(/|/); $names->[$line] = $title; $titles->[$line] = $url; } } } #->printNav # ExNet::General Print Out The Navigation Bar sub printNav { my( $names,$links ) = @_; if( $names==0 || "" or $links==0 || "" ) { errorDie("You did not specify a referrence to the names/links ar +ray. See \'perldoc ExNet::General\' for help.<br>\n"); } else { if( $names->[-1] == $links->[-1] and my( $count ) == $names->[-1 +] ) { my( $i ); print "<table width="100%" border="0" cellspacing="0" cellpadd +ing="0" height="25">\n<tr>\n<td height="25"> <div align=\"right\"><font face=\"",$GENV->{'EXNET_FONT +_FAMILY'},"\" size=\"2\">\n"; for( $i=0; $i<=$count; $i++ ) { print "[<a href=\"/cgi-local/exnet.pl?displayPage=\"",$names +->[$i],"\" class=\"NavBar\" onMouseover=\"setStatBar(\'",$names->[$i] +,"\'); return true;\">",$names->[$i],"</a>] \n"; } print "</font></div></td></tr><tr><td bgcolor=\"#000099\" heig +ht=\"25\"><font face=\"",$GENV->{'EXNET_FONT_FAMILY'},"\" size=\"2\" +color=\"#FFFFFF\"> &nbsp;EMCBi ExtraNet Server &raquo; PAGE</font></td></tr><tr>< +td>&nbsp;</td></tr></table>\n"; } else { errorDie("There are not an equal amount of array keys. See \'p +erldoc ExNet::General\' for help.<br>\n"); } } } #->returnPasswd # ExNet::General MD5 Checksum Generator sub returnPasswd { my( $password ) = @_; if( $password==0 || "" ) { errorDie("You did not parse a string to function function: retur +nPasswd(); See \'perldoc ExNet::General\' for help.<br>\n"); } else { $password = md5( $password ); return $password; } } #->errorWarn # ExNet::General Warn() Handler sub errorWarn { my( $error ) = $_[0]; print $error; } #->errorDie # ExNet::General Die() Handler sub errorDie { my( $error ) = $_[0]; print $error; exit(0); } 1; __END__ # ------------------------------------------------------------------ +---------------------- # # END Exported Methods - Begin POD + # # ------------------------------------------------------------------ +---------------------- # =head1 TITLE ExNet::General =head1 NAME ExNet::General - General functions for the ExtraNet Server =head1 SYNOPSIS use ExNet::General; $gen = new ExNet::General; $gen->returnPasswd( "foobar" ); =head1 DESCRIPTION This module implements the General functions. At the moment these methods are supported: =item C<new> Returns a new General object =item C<returnRef> Returns a referrence to the GLOBAL_ENV hash, allowing the user to vi +ew/edit it's values. It's second argument must be the string GLOBAL. =item C<getURLS_File> Opens and parses the urls.txt file for use in the printNav method. T +wo array referrences must be parsed to this hook. In the order of @names and @links. =item C<printNav> Print's out the navigatiomn bar for the EMCB ExtraNet Server. =item C<returnPasswd> Returns the MD5 sum of a string parsed to this hook. =item C<errorWarn> A method similar to Carp::warn; but without the kick-backs. =item C<errorDie> A method similar to main::die; but supplies it's own error messages +instean of using $errno. =back =head1 CHANGES This module is still in alpha release. =head1 EXAMPLE This example will load the module, parse the urls.txt file and print + out the EMCB ExtraNet Server - Navigation toolbar. #! /usr/local/bin/perl use ExNet::General; use strict; my $general = new ExNet::General; my $options = $general->returnRef( "GLOBAL" ); $options->{'EXNET_URLS_FILE'} = 'localpath/to/file/urls.txt'; my( @names,@links ); $general->getURLS_File( \@names,\@links ); printNav( \@names,\@links ); =head1 AUTHOR INFORMATION (C)Copyright 1999 - 2002, Elfyn McBratney. All Rights reserved. This library is free software; you can redistribute and/or modify it + under the same terms as perl itself. Address bug reports and comments to: elfyn@exposure.org.uk. When se +nding bug reports, please provide the version of General.pm, the version of Perl, the n +ame and version of your Web server, and the name and version of the operating system you are + using. If the problem is even remotely browser dependent, please provide informati +on about the affected browers as well. =cut

Any 'wisdom' or advice would be grately appreciated.

Cheers,

Elfyn

Edit: chipmunk 2002-02-24

Replies are listed 'Best First'.
Re: Creating my first perl mod
by hossman (Prior) on Feb 25, 2002 at 04:22 UTC
    Every line of your code (including your __END__ and all of your pod commands) is indented by two spaces (at least, in the version you submitted it is)

    As I understand it, pod requires that all of your commands (ie: =head1) be left aligned. (no indent)

    When I change your TITLE to NAME, and remove the two spaces on that line, i get a valid POD doc that only has a title (nothing else).

    You might wnat to take a look at podchecker (which should come with perl >= 5.6)

      You might wnat to take a look at podchecker.

      If only it could understand all legal POD syntax (like =head3).

      --
      Ilya Martynov (http://martynov.org/)

        Hi,

        thanks for the comments. I was led to beleive that pod can be on an indented line, so that's how i did it. Now i know it wont ill change my editor-api to not use indentations on pod. Thanks for all the comments.

        Does anyone see any problems with the actual perl code?

        Cheers,

        Elfyn

Re: Creating my first perl mod
by IlyaM (Parson) on Feb 25, 2002 at 02:50 UTC
    Your POD documentation doesn't need section TITLE. Correct POD should start with section NAME:
    =head1 NAME ExNet::General - General functions for the ExtraNet Server =head1 SYNOPSIS .... ....

    --
    Ilya Martynov (http://martynov.org/)

Re: Creating my first perl mod
by emcb (Beadle) on Feb 25, 2002 at 03:10 UTC
    I tried that and i still get the same error message.