Code to generate nice html pages from POD files
Fetching latest commit…
Cannot retrieve the latest commit at this time
-------------------- - 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 (firstname.lastname@example.org) HISTORY This code is based on the code written by Jon Allen (JJ) <email@example.com> 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. templates/XX/ 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?