• perldoc.org -

DESCRIPTION

This archive contains the source code for the website http://perldoc.org, which holds the translated versions of the core documentaion for Perl in HTML and PDF formats as they were released in the POD2::* namespace on CPAN.

USAGE

mkdir cache mkdir out mkdir out/fr mkdir out/it mkdir src cd src wget http://search.cpan.org/CPAN/authors/id/P/PO/POLGAB/POD2-FR-0.03.tar.gz tar xzf POD2-FR-0.03.tar.gz wget http://search.cpan.org/CPAN/authors/id/E/EN/ENRYS/POD2-IT-0.12.tar.gz tar xzf POD2-IT-0.12.tar.gz cd ..

perl scripts/build.pl

Individual scripts (will be changed)

perl build-perldoc-pdf.pl --output-path /path/to/output perl build-perldoc-static.pl --output-path /path/to/output perl build-perldoc-html.pl --output-path /path/to/output --input-path /usr/share/perl/5.10/pod/ --cache syntax.cache

To create localized versions of perldoc: Download POD2::XX from CPAN and unzip it to some directory.

French

It took 16 minutes to process the French files. (BTW the French docs are also available here: http://perl.enstimac.fr/DocFr.html )

Italian

http://pod2it.sourceforge.net/pods/

NOTES

Please be aware that this software was written for the specific purpose of generating the perldoc.perl.org website, and not to solve generic problems like "convert a directory of Pod to HTML" or "produce documentation for Perl and all modules installed on my system". However, the templates, CSS, and conversion routines should give you a head start should you wish to write a more generic tool.

LICENSE

Unless stated otherwise, all files are Copyright (C) 2008 Jon Allen and distributed under the terms of the Artistic License version 2.0.

The Perl Onion logo is a trademark of The Perl Foundation. See http://www.perlfoundation.org/perl_trademark for usage details.

CONTACT

Gabor Szabo ([email protected])

HISTORY

This code is based on the code written by Jon Allen (JJ) [email protected] that creates the http://perldoc.perl.org/ website. See also http://perl.jonallen.info/projects/perldoc

It was released under the Artistic 2 license on 24 December 2008 http://use.perl.org/~jj/journal/38153

Uploaded to Github by Gabor Szabo and changed. I don't have information about how http://perldoc.perl.org/ is generated. This code is now used to generate the perldoc.org subsites.

LANGUAGE SPECIFIC ISSUES

Here we are going to collect the information we need to add a new language.

static-html/XX/index.html is the content of the front page of each language.

COMMENTS and TODO

The package that was distributed by Jon Allen included a modified copy of version 0.17 of the Pod::POM module in the lib/ directory. It was removed. we should see if the new version of Pod::POM provides what is needed.

Initial processing is very slow but once the cache is ready subsequent processing is fast. So adding a new language or upgrading a version of the documentation will take a lot of time (~ 15 min / language on my notebook) but subsequent rebuilds of the site is quick.

One ran of Devel::NYTProf after shortcutting the processing loop pointed to a large number of calls to GetOptions internals possibly by Perl::Tidy.

The syntax.cache needs some improvement maybe saving file-by-file in a cache directory?

The input-path was added as the directories were not discovered correctly on my computer. This needs to be cleaned up.

How do we generate the main index.html page ?

Include an about page in each language to explain how to get involved in the translation.

Contact information of the translators.

Contact info of site maintainer.

Include the version number of each POD2:: release that has been used to generate the page.

Links to the main site and from there to the individual translation sites.

Index the X<> and the C<> tags

Make it clear these documentations are not the full translations and that they might not correspond exactly to the version of perl they have installed on their system.

Make it clear how one can start the translation effort in his own language?

Make sure the site can be built on any machine and that the pages can be used off-site in a nice way.

Have information available in English and in the local language about who maintains the translations and where to find them. Where to find the source code used to process this. On who is hosting the web site in case it is not accessible.

Contact all the translators as I find them and talk to them about keeping the POD2:: package up to date on CPAN (and in general packaging their translations to POD2:: files) and helping with the development of the code that produces the website.

Process

download latest version of all the POD2::* files from CPAN process each one of them

Long term plan:

Allow people to add comments similar to what happen on php.net http://php.net/manual/en/function.printf.php or shall we keep the entrance erquirement a bit higher but centralized to each language?