Saudações amigos do PHP-AM,

O PHP é sem dúvida a linguagem de programação mais bem documentada atualmente, já são mais de 10000 páginas de documentação disponíveis. E, para manter toda essa fonte de valiosa de dados, existem pessoas do mundo inteiro colaborando com o Manual e suas traduções, que é claro são open source. Neste post, vamos aprender como baixar e renderizar o Manual do PHP, primeiro passo para começar a contribuir com o Manual.

Todo o repositório do PHP foi migrado do CVS para o SVN recentemente, então, para baixar os fontes do manual, primeiramente certifique-se de ter uma cópia do Subversion instalada em sua máquina. Para baixar o manual faça:

$ svn co http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc

Este comando criará a pasta phpdoc com os fontes do manual em inglês. Para baixar a documentação em português apenas substitua o doc-en por doc-pt_BR. A seguinte estrutura de diretórios será criada:

phpdoc/
- doc-base/
- en/

O diretório en/ possui o Manual propriamente dito, que é escrito no formato DocBook 5. Já o diretório doc-base possui vários scripts para manutenção do manual. Para configurar o manual faça o seguinte.

$ cd phpdoc/doc-base/
$ php configure.php

Se tudo der certo, ao final deste passo, o arquivo (gigantesco) .manual.xml deverá ser gerado. Este arquivo possui todo o manual formatado para que o PhD possa entrar em ação.

O PhD: [PH]P Based [D]ocBook Renderer é a ferramenta que renderiza o Manual nos diversos formatos disponíveis no php.net xhtml, pdf, chm etc. O próprio Manual online também é renderizado com o PhD. Como o PhD sempre utiliza a última versão do PHP, trate de instalar o PHP 5.3 se você anda meio desatualizado. Você também precisará do PEAR instalado em sua máquina. Para instalar o PhD faça:

$ pear install --alldeps doc.php.net/phd-beta

Com o PhD instalado já podemos renderizar o Manual, vamos testar o formato xhtml:

$ phd --docbook path/to/.manual.xml --format xhtml --package PHP --output manual

O PhD irá gerar os arquivos dentro do diretório manual/. O formato xhtml gerará o Manual em milhares de arquivos .html. Para testar faça:

$ firefox manual/php-chunked-xhtml/index.html

Agora você pode renderizar o Manual do PHP em sua máquina na hora que quiser \o/. O PhD possui outros formatos de saída como PDF e Manpages, para visualizar todos faça:

$ phd --list

Bem, esta é a configuração básica de qualquer contribuidor do Manual do PHP, se você quiser fazer alguma alteração no manual modifique os arquivos fonte no seu diretório phpdoc/en ou phpdoc/pt_BR e então rode novamente o configure.php e o PhD, e as suas modificações poderão ser vistas no seu browser.

O PhD também é utilizado para renderizar o Manual do PEAR e arquivos DocBook em geral. Qualquer dúvida com relação ao Manual ou o PhD envie um e-mail para a lista phpdoc@lists.php.net, ou acesse o canal #php.doc no EFNet. No próximo post darei mais dicas de como utilizar o PhD e contribuir com o Manual do PHP.

Abraço e até a próxima.