ActiveState Perl User Guide -- how can I add an entry to the list of Programs?

[clyde.ingram]

When I install my own module, or one from a PPM repository, onto a PC
running ActiveState Perl, a documentation entry appears for this in
the Modules section of my ActiveState Perl User Guide. So far, so
good.

But how can I install my own executable Perl program/script such that
a documentation entry appears for the new program in the Programs
section of the User Guide?

I am starting with my Perl program "ckscan.pl", plus an HTML file
"ckscan.html" generated from the program using pod2html.

When I access the ActiveState User Guide c:/Perl/html/index.html, the
file c:/Perl/html/perltoc.html seems to be regenerated to update the
Modules and Programs panels. What do I have to configure so that my
new program is picked up in the Programs part of perltoc.html?

Simply dropping my html file "ckscan.html" or my program "ckscan.pl"
into c:/perl/bin has no effect.

Thank-you for any constructive advice,
Clyde

 

[Ben Morrow]

Quoth (e-mail address removed):

When I install my own module, or one from a PPM repository, onto a PC
running ActiveState Perl, a documentation entry appears for this in
the Modules section of my ActiveState Perl User Guide. So far, so
good.

But how can I install my own executable Perl program/script such that
a documentation entry appears for the new program in the Programs
section of the User Guide?

If you have installed your program/modules correctly (i.e., under
C:\Perl\site\lib or C:\Perl\bin), and they have embedded POD, you can
regenerate all the HTML documentation from the POD by running

perl -MActivePerl:ocTools -eUpdateHTML

.. Note that this will take quite a while to run.

I am starting with my Perl program "ckscan.pl", plus an HTML file
"ckscan.html" generated from the program using pod2html.

When I access the ActiveState User Guide c:/Perl/html/index.html, the
file c:/Perl/html/perltoc.html seems to be regenerated to update the
Modules and Programs panels.

Err.. no. That's impossible. What happens is that whenever you install
something with PPM, the TOC page is regenerated.

What do I have to configure so that my
new program is picked up in the Programs part of perltoc.html?

Simply dropping my html file "ckscan.html" or my program "ckscan.pl"
into c:/perl/bin has no effect.

If you put your HTML page in the correct place (C:\Perl\html\bin), you
should be able to run

perl -MActivePerl:ocTools -eActivePerl:ocTools::WriteTOC

to just update the TOC. Note: I've never tried this, but it is what PPM
does after installing anything.

A third option would be to package your script up into a proper
distribution, use MakeMaker to create a PPD, and install that using PPM.

Ben

 

[clyde.ingram]

Err.. no. That's impossible. What happens is that whenever you install
something with PPM, the TOC page is regenerated.

I agree. My error. I've been installing modules at this time too.

If you put your HTML page in the correct place (C:\Perl\html\bin), you
should be able to run

perl -MActivePerl:ocTools -eActivePerl:ocTools::WriteTOC

to just update the TOC.

Ben, that works for me. Thank-you.

A supplementary problem is how to link to other pages in the manual.
Eventually I want to link to one of my new modules in ActiveState.
But to start with somethin simple (!), the perlpod page tells me I can
insert, for example:

<QUOTE>
L<name> -- a hyperlink <> >>
There are various syntaxes, listed below. In the syntaxes given, text,
name, and section cannot contain the characters '/' and '|'; and any
'<' or '>' should be matched.

L<name>

Link to a Perl manual page (e.g., L<Net:ing>). Note that name should
not contain spaces.
</QUOTE>

So, I insert this POD paragraph:

L<Net:ing>

just like the man said. But the link on my new "ckscan" page in
ActiveState under "Programs" looks like this (underlined):

the Net:ing manpage

but resolves to this URL:

file:///Net/Ping.html

That URL does not work. What should L<Net:ing> resolve to, and how
can I make it resolve in this way?

Regards,
Clyde Ingram

 

[Ben Morrow]

Quoth (e-mail address removed):

Ben, that works for me. Thank-you.

A supplementary problem is how to link to other pages in the manual.
Eventually I want to link to one of my new modules in ActiveState.
But to start with somethin simple (!), the perlpod page tells me I can
insert, for example:

<QUOTE>
L<name> -- a hyperlink <> >>
There are various syntaxes, listed below. In the syntaxes given, text,
name, and section cannot contain the characters '/' and '|'; and any
'<' or '>' should be matched.

L<name>

Link to a Perl manual page (e.g., L<Net:ing>). Note that name should
not contain spaces.
</QUOTE>

So, I insert this POD paragraph:

L<Net:ing>

just like the man said. But the link on my new "ckscan" page in
ActiveState under "Programs" looks like this (underlined):

the Net:ing manpage

but resolves to this URL:

file:///Net/Ping.html

That URL does not work. What should L<Net:ing> resolve to, and how
can I make it resolve in this way?

Well, obviously, L<Net:ing> should resolve to
file:///c:/Perl/html/lib/Net/Ping.html or some such. If you use
UpdateHTML instead of generating the HTML yourself with pod2html it
should get it right; otherwise, see the --htmlroot option to pod2html.

Ben

 

[clyde.ingram]

Quoth (e-mail address removed):



A third option would be to package your script up into a proper
distribution, use MakeMaker to create a PPD, and install that using PPM.

How should I exploit Ben's 3rd option: packaging and using MakeMaker?

So far, I have a package for a .pm file: I created the framework
using:

module-starter --module=MyModule --author=... --email=...

and I shovelled my code and POD into the framework lib/MyModule.pm.
This installs very nicely using commands:

nmake
nmake install

with the new HTML page (from my POD source) appearing nicely under the
ActiveState Modules section.

Better still, I can configure links to an HTML page for a new Perl
program, say myprog.pl, which appears under the ActiveState Programs
section. Following Ben's good advice, myprog.pl installs using the
verbose commands:

pod2html --infile=c:/mystuff/myprog.pl --outfile=c:/Perl/html/bin/
myprog.pl --htmlroot=file:///c:/Perl/html
perl -eActivePerl:ocTools -eActivePerl:ocTools::WriteTOC

However, instead of the last 2 commands, I'd like to construct an
installable module for myprog.pl. Perhaps bundle it somehow with
MyModule.pm.
How can I do this?

The manual for ExtUtils::MakeMaker::Tutorial itemises a bin directory
at the same level as the MANIFEST, Makefile.PL, lib, etc. Oddly, it
gives no clues on how to use the bin directory. So i dropped
myprog.pl into the bin, added "bin/myprog.pl" to the MANIFEST, and re-
ran:

perl Makefile.PL
nmake
nmake install

No luck. myprog.pl did no appear in the ActiveState help; no
myprog.pl or myprog.html files appeared under c:/Perl.

Have I got to define something in Makefile.PL to do with INST_SCRIPT
or INSTALLSCRIPT, for example?

Thank-you,
Clyde

 

[Ben Morrow]

Quoth (e-mail address removed):

How should I exploit Ben's 3rd option: packaging and using MakeMaker?

So far, I have a package for a .pm file: I created the framework
using:

module-starter --module=MyModule --author=... --email=...

and I shovelled my code and POD into the framework lib/MyModule.pm.
This installs very nicely using commands:

nmake
nmake install

with the new HTML page (from my POD source) appearing nicely under the
ActiveState Modules section.

Better still, I can configure links to an HTML page for a new Perl
program, say myprog.pl, which appears under the ActiveState Programs
section. Following Ben's good advice, myprog.pl installs using the
verbose commands:

pod2html --infile=c:/mystuff/myprog.pl --outfile=c:/Perl/html/bin/
myprog.pl --htmlroot=file:///c:/Perl/html
perl -eActivePerl:ocTools -eActivePerl:ocTools::WriteTOC

However, instead of the last 2 commands, I'd like to construct an
installable module for myprog.pl. Perhaps bundle it somehow with
MyModule.pm.
How can I do this?

The manual for ExtUtils::MakeMaker::Tutorial itemises a bin directory
at the same level as the MANIFEST, Makefile.PL, lib, etc. Oddly, it
gives no clues on how to use the bin directory. So i dropped
myprog.pl into the bin, added "bin/myprog.pl" to the MANIFEST, and re-
ran:

perl Makefile.PL
nmake
nmake install

perldoc ExtUtils::MakeMaker says you need to add an entry

EXE_FILES => ['bin/myprog.pl'],

to your Makefile.PL. Recommended practice would be to puth the bulk of
your code into the module, and have the executable just parse the
command-line and call into the module. Remember to put POD in the
executable as well, as this is what will appear under the executables
section of the TOC.

Ben

 

[clyde.ingram]

i dropped
myprog.pl into the bin, added "bin/myprog.pl" to the MANIFEST, and re-
ran:

perl Makefile.PL
nmake
nmake install

No luck. myprog.pl did no appear in the ActiveState help; no
myprog.pl or myprog.html files appeared under c:/Perl.

Part solution: I dropped myprog.pl into blib/bin, and re-ran:

perl Makefile.PL
nmake
nmake install

This time, myprog.pl appears under the Programs section in ActiveState
Perl help page, as required.
However, links are broken again. When I click on a link which POD
defined like this:

L<MyModule|site::lib::MyModule>

my browser (Firefox) complains of failure to find:

/C:/Perl/html//mystuff/MyModule/blib/html/site/lib/MyModule.html

The link should resolve to:

C:/Perl/html/site/lib/MyModule.html

Now, this works when I use the pod2html command, specifying --
htmlroot="file:///C:/Perl/html".
How do I configure my Makefile.PL to override the default htmlroot, to
get the same effect as the --htmlroot switch on the pod2html command?

Regards,
Clyde

 

[clyde.ingram]

perldoc ExtUtils::MakeMaker says you need to add an entry

EXE_FILES => ['bin/myprog.pl'],

to your Makefile.PL. Remember to put POD in the
executable as well, as this is what will appear under the executables
section of the TOC.

Done. And its web page appears nicely in the ActiveState Programs
panel.
Thank-you for such a fast response.

But I still have the problem of how Makefile.PL is to redefine the
htmlroot, in the way that pod2html uses the --htmlroot switch.
Details are on a separate posting of 40 minutes ago.

Regards,
Clyde