SmartLinks on CPAN now

In "What is the last element of an infinite list or how to get started with Perl 6 ?" I mentioned the smart-links, a nice feature that can help learning Perl 6. Now it is available for any Perl 5 developer too.

In the test files of Perl 6 developers can embed so called smart-links that point to various sections of the Perl 6 documentation, also known as the Synopsis. Then running the smartlinks.pl script will generat HTML versions of the documentation and will embed parts of the test files in the marked places.

That allows the reader of the documentation to see the relevant test cases by one click.

You can see the generated Perl 6 documentation. Click on any of the Synopsis links in that page.

A smart-link is basically just a comment that looks like this:

# L

Where the "Section name" is one of the =head1 or =head2 entries in the pod.

Actually the same links could be also used to allow someone editing the test files to jump right to the relevant documentation if only there was an editor supporting it...

On the Hackathon last week after the Nordic Perl Workshop I started to refactor the single-file smartlinks.pl script. Removed most of the Perl 6 and Pugs specific parts and moved the code to a module. Some more work yesterday and today and finally I could create [dist://Text::SmartLinks], a CPAN package that provides this functionality to any code that has documentation in POD format and tests.

The generated HTML files still remind us that it originated from the Perl 6 code-base but the module is already usable.

TODO

I have some plans to allow the processing to interact with other POD processors so this can be reused by any web site that generates documentation for perl code. Probably the whole HTML generating back-end should be separated out and then we can use the package in other tools as well.

Try it and if you'd like to help out with the development of the module, you can easily get a commit bit as the code lives in the SVN repository of Pugs.

I'd like to thank to Agent Zhang who originally wrote the code and the Pugs team that maintains it.