Perlmonks already has some Perl documentation online, available under the various keywords of the documentation, mostly perlman: and perlfunc:. When mentioning module names like HTTP::Message, the engine dosen't find that node here and on the Not found-page, there is a hint like "Maybe you want the CPAN information for HTTP::Message. What I would like would be another prefix like for example CPAN: so I could reference documentation for a module available on CPAN directly from a node. The engine for that should be relatively simple if there is any provision of parsing node links for a prefix. Another addition along the same lines would be a link to the RFCsearch engine so that RFCs could be referenced using RFC:2068.

Of course, all of this can already currently be done by looking up the "right" link and using , so it's not really necessary but the lazy ones among us (that is, I :)) would benefit from that, as would the persons needing the links to RFCs and CPAN documentation.

Replies are listed 'Best First'.
RE: Direct links to module documentation
by Corion (Patriarch) on Jun 03, 2000 at 17:56 UTC

    D'oh - I messed up the quoting on that node and I can't even edit and change it ... Stupid me :(

    So here's the "real" version :

    Perlmonks already has some Perl documentation online, available under the various keywords of the documentation, mostly perlman: and perlfunc:. When mentioning module names like HTTP::Message, the engine dosen't find that node here and on the Not found-page, there is a hint like "Maybe you want the CPAN information for HTTP::Message.

    What I would like would be another prefix like for example CPAN: so I could reference documentation for a module available on CPAN directly from a node. The engine for that should be relatively simple if there is any provision of parsing node links for a prefix. Another addition along the same lines would be a link to the RFCsearch engine so that RFCs could be referenced using [RFC:2068].

    Of course, all of this can already currently be done by looking up the "right" link and using <A href="...">, so it's not really necessary but the lazy ones among us (that is, I :)) would benefit from that, as would the persons needing the links to RFCs and CPAN documentation.

[reply]
RE: Direct links to module documentation
by KM (Priest) on Jun 04, 2000 at 03:16 UTC
    I think this would be somewhat of a pain to work out. This is because how are you going to know what version of module is newest to point to the docs? Something on the backend would need to search CPAN for the latest version of module X, then link to the appropriate README, every single time the page was loaded. Why every time? Because if you link to it on version 0.01, and tomorrow it is updated to 0.02, you don't want to be sending people to outdated docs. Personally, I think this is more expensive than needed. Also, much of the time the only thing to point to on CPAN is the README (which is extracted by default on CPAN), but that doesn't always include the actual POD docs (some just say how to install the module). Just as with the Perl docs, I think it is better to tell people to go to CPAN and look at the docs themselves to make sure people see the most relevent information for themselves.

    Cheers,
    KM

[reply]
RE: Direct links to module documentation
by mdillon (Priest) on Jun 03, 2000 at 22:35 UTC
    i like the general idea of allowing easier access to external resources like CPAN and RFCs, but how should it work?

    should CPAN:* links go to a page on Perl Monks that has a link to the relevant CPAN resource? or are you proposing an implementation based on a redirector?

[reply]

      My idea was a link to another search engine with the "right" search parameters. Maybe some code will clear this up : 

        my $userlink = "[CPAN:File::Find]";
  # or alternatively
  my $userlink = "[RFC:2068]";

  ...

  if ($userlink =~ /^\[CPAN:(.*?)]$/) {
    $HTMLlink = "<A href=\"http://search.cpan.org/search?mode=module&q
+uery=$1\">$1</A>";
  };
  if ($userlink =~ /^\[RFC:(.*?)]$/) {
    $HTMLlink = "<A href=\"http://www.rfc-editor.org/cgi-bin/rfcsearch
+.pl? ... $1\">RFC $1</A>"; # I'm not sure if
    # RFCsearch will work with a link or if it wants
    # a form ...
  };

      [download]
      So we would have "smart" outside links that send the user directly to an external search engine.

      This would mean, that the user always gets sent to what that search engine thinks is current, which can be good or bad, but thinking how often I get sent to the Not found page and have to do the second click on "Maybe you want to ask CPAN", I think it would be a good idea to save that click ...

[reply]
[d/l]
        what about editing a node? will the user editing the node see their original shortcut link, or will they see the expanded link?

        if you can't easily edit these links afterward, then their value is not as great. on the other hand, i doubt that the expense of generating real links on-the-fly or storing two copies of the node text (source and expanded) are worth it either.

        i think that having these sort of links go to a separate page that lists the full link and perhaps redirects after 5 to 10 seconds would be the most maintainable implementation.

        that way, the author can simply edit the original text, the user will have a chance to see what resource their being sent to (and a chance to cancel), and it can be forward and backward compatible (as long as there's no links with titles matching /^(?:(RFC):(\d+)|(CPAN):(\w+(?:::\w+)*))$/ ).

[reply]
RE: Direct links to module documentation
by lhoward (Vicar) on Jun 04, 2000 at 04:58 UTC
    I think this is a great idea. In a "Perl Monks Discussion" a while ago I suggested putting the docs for all CPAN modules on Perlmonks (in the library). Doing that would make it easy to make the links point to the right place w/o involving an outside site that we do not have direct controll over (a-la search.cpan.org). I think the "CPAN module links" should point to the module's documentation, the module can already be installed easily enough by using the CPAN module itself. The RFC link would be great too.. and particularly easy to implement since RFC's use a simple numbering scheme.
[reply]

      Having the complete documentation available on the site would be a cool thing, but I think there are some problems with that idea :

      Keeping the documentation current would be difficult, as every updated module would have to be downloaded from CPAN and the documentation would have to be generated (I guess that make documentation is not really standard).

      The storage available to Perlmonks is not unlimited and I rather download the Not found page and click on the CPAN search link than missing some Haikus or some interesting question here - maybe vroom could comment on how scarce disk space is for Perlmonks :).

[reply]
        Before I found search.cpan.org I had started a project to build a complete CPAN module documentation site. I already had the system partly developed and still have the code kicking around.

        It is easy to automatically scan through CPAN on a scheduled basis and spot new/changed modules (thank to the CPAN modules page). I don't think that detecting module version changes in real-time is necessary as most people don't upgrade modules the minute a new version comes out. If you really want to split hairs on this issue you would need to have the docs for EVERY version of EVERY module. I don't think this granularity is necessary. Modules (and their documentation) generally don't change significantly from version to version, so any recent version of the documentation for a module would be sufficient for anything but the most percise needs (not to even mention that the docs aren't always up-to-date with the code). A nightly update would be more than adequate.

        I did some metrics and found that the average module had about 8 K of POD documentation throughout all of its files. There are currently about 1500 modules on CPAN. Alowing a generous buffer for added markup all the documentation should fit in under 20 MB. Not a lot of space to ask for in today's world.

        Also I do not have %100 confidence in search.cpan.org as I sometimes find module documentation missing.

        I would be happy to devote my time, expertise and my partially developed system to bring complete CPAN documentation on as a Perlmonks feature.

[reply]

Back to Perl Monks Discussion