About Perldoc

A brief history

The first web-based perldoc started October 2000[1]. In later years, it had reliability issues due to demand and had outgrown the original platform.

It was picked up by JJ Allen in January 2005 as “the result of a project to produce a version of the Perl documentation set suitable for off-line use.”[2] and originally hosted at perldoc.perldrunks.org.

During the QA Hackathon Rugby 2016, Babs Veloso, who has worked on a number of other perl.org websites, came up with the visual design and developed the front-end code

.

John Mica and Paul Webster from OpusVL then re-wrote the back-end from my previous version (while fixing a lot of bugs and improving the build process). They integrated Babs’s front-end designs and worked with Ask and Robert from Perl.org on the hosting and deployment. Then, after a testing phase with a few other members of the community, the new site was launched.

How does it work?

A key requirement for perldoc is performance, reliability, ability to download for local use and mirroring.

Therefore perldoc.perl.org is built using a static site generator rather than being served dynamically.

The HTML output of the build process is pushed to a shared git repository from which perl.org pulls on a regular basis.

Anyone can ‘git clone’ the full site if a local / offline copy is required.

Should the maintainer go AWOL, anyone else can pick up the builder code from GitHub and be granted access to push to perl.org’s repo.

daily build process

reads CPAN daily for new versions of Perl

if so, downloads Perl and compiles it

then rebuilds documentation set from scratch

changes to templates from git also get processed daily

builds local instance of compiled files, git commit and push

hosted server git pulls to load the site, then statically served

This model fits with the perl.org infrastructure (eg, supports geographical mirroring), and importantly it allows the site to be independent of any third party maintainer or hosting environment - everything is within perl.org’s control.