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

Discussion in 'Perl Misc' started by clyde.ingram@edl.uk.eds.com, Mar 5, 2007.

  1. Guest

    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
    , Mar 5, 2007
    #1
    1. Advertising

  2. Ben Morrow Guest

    Quoth :
    > 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::DocTools -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::DocTools -eActivePerl::DocTools::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

    --
    You poor take courage, you rich take care:
    The Earth was made a common treasury for everyone to share
    All things in common, all people one.
    'We come in peace'---the order came to cut them down. []
    Ben Morrow, Mar 5, 2007
    #2
    1. Advertising

  3. Guest

    On 5 Mar, 20:50, Ben Morrow <> wrote:
    > > 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.


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

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

    >
    > If you put your HTML page in the correct place (C:\Perl\html\bin), you
    > should be able to run
    >
    > perl -MActivePerl::DocTools -eActivePerl::DocTools::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::ping>). Note that name should
    not contain spaces.
    </QUOTE>

    So, I insert this POD paragraph:

    L<Net::ping>

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

    the Net::ping manpage

    but resolves to this URL:

    file:///Net/Ping.html

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

    Regards,
    Clyde Ingram
    , Mar 7, 2007
    #3
  4. Ben Morrow Guest

    Quoth :
    > On 5 Mar, 20:50, Ben Morrow <> wrote:
    > > Quoth :

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

    > >
    > > If you put your HTML page in the correct place (C:\Perl\html\bin), you
    > > should be able to run
    > >
    > > perl -MActivePerl::DocTools -eActivePerl::DocTools::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::ping>). Note that name should
    > not contain spaces.
    > </QUOTE>
    >
    > So, I insert this POD paragraph:
    >
    > L<Net::ping>
    >
    > just like the man said. But the link on my new "ckscan" page in
    > ActiveState under "Programs" looks like this (underlined):
    >
    > the Net::ping manpage
    >
    > but resolves to this URL:
    >
    > file:///Net/Ping.html
    >
    > That URL does not work. What should L<Net::ping> resolve to, and how
    > can I make it resolve in this way?


    Well, obviously, L<Net::ping> 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

    --
    You poor take courage, you rich take care:
    The Earth was made a common treasury for everyone to share
    All things in common, all people one.
    'We come in peace'---the order came to cut them down. []
    Ben Morrow, Mar 7, 2007
    #4
  5. Guest

    On 5 Mar, 20:50, Ben Morrow <> wrote:
    > Quoth :
    >
    > > 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?

    >
    >
    > 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::DocTools -eActivePerl::DocTools::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
    , Mar 14, 2007
    #5
  6. Ben Morrow Guest

    Quoth :
    > On 5 Mar, 20:50, Ben Morrow <> wrote:
    > > Quoth :
    > >
    > > > 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?

    > >
    > >
    > > 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::DocTools -eActivePerl::DocTools::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

    --
    I've seen things you people wouldn't believe: attack ships on fire off
    the shoulder of Orion; I watched C-beams glitter in the dark near the
    Tannhauser Gate. All these moments will be lost, in time, like tears in rain.
    Time to die.
    Ben Morrow, Mar 14, 2007
    #6
  7. Guest

    On 14 Mar, 13:52, wrote:

    > 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
    , Mar 14, 2007
    #7
  8. Guest

    On 14 Mar, 15:53, Ben Morrow <> wrote:
    > 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
    , Mar 14, 2007
    #8
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Vittorio

    Boxed Perl or ActiveState Perl?

    Vittorio, Apr 1, 2004, in forum: Perl Misc
    Replies:
    3
    Views:
    175
    GreenLight
    Apr 2, 2004
  2. Jake Wiley
    Replies:
    14
    Views:
    286
  3. Arvin Portlock
    Replies:
    11
    Views:
    253
    Arvin Portlock
    Jul 4, 2005
  4. Casey Hawthorne
    Replies:
    14
    Views:
    435
  5. Dilbert
    Replies:
    0
    Views:
    829
    Dilbert
    Nov 10, 2011
Loading...

Share This Page