John M. Dlugosz has asked for the wisdom of the Perl Monks concerning the following question:

When I install a package via ppm, the POD gets converted to HTML and the left-hand pane of the frameset gets rewritten to include the new files.

How can I trigger this process, to re-scan the existing HTML files and make a new index pane? I'll do that after making changes, adding modules that are not done with PPM.

—John

Replies are listed 'Best First'.
Re: ActiveState's HTML documentation
by dvergin (Monsignor) on Jul 28, 2001 at 01:08 UTC
    As chance would have it, Rudif has contributed Update HTML Doc with exactly this problem in mind. As he says in the intro on that page:

    ...in several circumstances you may wish to use this script here, to convert pod found in module files to html and/or to update the TOC:

        1. you added html files found on the web
        2. you installed a module from CPAN whose files contain pod
        3. you installed your own scripts or modules containing pod
     

[reply]
Re: ActiveState's HTML documentation
by HyperZonk (Friar) on Jul 28, 2001 at 01:09 UTC
    You may want to take a look at the modules in ActivePerl::DocTools. The processing is done by subs in those modules, notably in ActivePerl::DocTools::WriteTOC(). There is module documentation for this, but unfortunately it is scanty and incomplete. I spent a couple of minutes looking at the mods themselves, and at a brief glance it looks like it should be relatively easy to figure out how to use them.

    Update: Oop! dvergin got in ahead of me, and has actually pointed you to a script that implements the modules I mentioned. Good show, dvergin!

    -HZ
[reply]
[d/l]
Re: ActiveState's HTML documentation
by $code or die (Deacon) on Jul 28, 2001 at 05:26 UTC
    I second (third?) the advice for using Update HTML Doc.

    Since you are editing ActiveState's docs, you might want to check out perltoc.

    The author mentioned it on c.l.p.m. a couple of days ago. It adds a search box to the table of contents. You type in a regex directly. The neat thing is that it sets up a "client-side!" perl httpd to handle the requests.

    caveats: the author uses CGI but uses a home-grown query-string parser - easily fixed. Also, it's client side - so you need javascript turned on and perlscript needs to be enabled for local files. It therefore only works on IE in a windows environment.

    I modified the script to use the CGI.pm for fetching form values and to allow non-regex searches. I want to check with the author to see if it's ok to post the modified code here.

    Alternatively, I might just rewrite it using server-side code to do the searching - it would be more secure. The problem with that is that you'd need to run the activestate docs through a real webserver.

    Error: Keyboard not attached. Press F1 to continue.
[reply]
      Hi $code_or_die,

      After posting a couple of mods (I made changes to the search engine part and the install part) and bugfixes that I made to the author of the script you mention he asked me to take over maintainance of it.

      Ive been planning to refactor it and would be very interested in seeing your copy. Perhaps we might merge whatever mods you have made and then we can post it both here and on the original website OpenPSP.Org (where the 'official' version still lives)? That way there aren't too many different versions running around confusing issues... :-)

      As for concerns about Javascript and the like I can see your point either way. I think the reason he uses a tiny snippet of JavaScript was that author knows it better than perl with regards to UI type stuff. The perlscript part (as well you know :-) only handles the creation of a virtual server and searching the files.

      Anyway, I personally think this whole idea has a lot of merit in the business world (intranet) and I certainly find the search engine a cool tool.

      Yves
      --
      You are not ready to use symrefs unless you already know why they are bad. -- tadmc (CLPM)

[reply]
      I'd thought about the feasability of adding a client-side search box. Note that PerlScript can run embedded in a web page, so it could be written in Perl, not Java.
[reply]
        Note that PerlScript can run embedded in a web page, so it could be written in Perl, not Java.

        Most of it is in "PerlScript". Just a tiny bit of javascript that could easily be done in perlscript.

        I just don't think I like "PerlScript"! It's fine if you are writing windows script components or otherwise using it through windows scripting host. But I think it was a bad mistake to make it useable through a web browser.

        It's restricted to IE 4 or higher with Windows 95 or above. And it only runs if you install that option through the ActivePerl install. I also think that it's very dangerous! Much more so that clientside javascript. With "Perlscript" you access the filesystem, Win32::* modules, databases, all without the end user knowing. Thank God that ActiveState has set the default to "enable Local" and not "enable Internet\All"



        Error: Keyboard not attached. Press F1 to continue.

        updated: added "s to bring more attention to the fact I am talking about "PerlScript" and not "Perl" - in the same way that "JavaScript" is not "Java"
[reply]

Back to Seekers of Perl Wisdom