--------------------
- 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 (szabgab@gmail.com)


HISTORY

This code is based on the code written by Jon Allen (JJ) <jj@jonallen.info>
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?