Existem agora dois sistemas diferentes de construção para o módulo php-gtk-doc; o padrão, usado no servidor e tento diversas opções para gerar, e o alternativo, o qual atualmente apenas oferece a versão em Inglês e a versão em multiplos arquivos HTML.

A vantagem principal do sistema alternativo é que ele faz ser possível compilar o manual do PHP-GTK no windows sem instalar um emulador de Linux como o cygwin. Você precisará, entretanto, várias versões nativas de Ferramentas Unix para poder criar um ambiênte para construi-lo. Instalar estas simplesmente significa descompacta-las no seu diretório raíz, assim esta é uma opção fácil se você não tem conectividade suficiente ou esta de outra maneira impedido de instalar o cygwin em seu computador local.

Quanquel que seja a opção de construção que você escolha, você precisará ter instalado o xsltproc para processar as planilhas de estilo XSL. Num sistema Linux, você pode instalar isto com o seu gerenciador de pacotes. Se você esta trabalhando no ambiênte cygwin, você pode adiciona-lo atráves do mecanismo de instalação do cygwin. Se você esta simplesmente usando o Windows, você pode copiar os binários do xsltproc (você vao precisar dos pacotes iconv, zlib, libxml2 e libxslt) de xmlsoft.org do contribuidor Igor Zlatkovic's pagina do projeto e discompactar no seu diretório raíz.

Antes que nós possamos modificar ou mesmo compilar o manual, nós precisamos obter uma cópia do CVS. Para realizar isto, você precisa de um cliente CVS. Praticamente em todos os sistemas Linux, a ferramenta de linha de comando cvs esta instalada. Isto esta disponível também atráves do cygwin. No windows existem clientes CVS nativos apontar-e-clicar disponíveis, como o Tortoise CVS.

Para obter uma copia dos documentos usando a ferramenta de linha de comando do cvs, digite: cvs -d :pserver:[email protected]:/repository co -P php-gtk-doc

Se você já tem uma copia, você pode atualiza-la via: cvs -d :pserver:[email protected]:/repository update -Pd php-gtk-doc (se você esta dentro do diretório php-gtk-doc, você pode (tem que) omitir a parte php-gtk-doc).

Para obter uma copia do módulo da documentação usando o TortoiseCVS: vá para File/CVS checkout e prencha o formulário. O protocolo é a opção Password server (:pserver); o servidor é cvs.php.net, e a pasta do repositório é /repository. Se você tem uma conta de CVS, por favor use o seu próprio nome de usuário; se não use cvsread; e o módulo, claro, é php-gtk-doc. Na versão atual do TortoiseCVS, os finais de linha são convertidos para o Windows por padrão; nós não queremos isso em qualquer lugar do repositório, assim se você quer enviar(commit) qualquer uma das suas modificações você deve ir em Options e marcar a caixa que diz Use UNIX line endings.

A partir da linha de comando, entre no diretório php-gtk-doc através do comando cd php-gtk-doc. Digite autoconf para criar o arquivo de configuração.

Existe suporte completo a internacionalização (i18n) neste sistema de construção, com a configuração padrão sendo Inglês (en). Se você esta compilando para qualquer outra língua que não seja o Inglês, você precisará definir na linha do configure o código da língua para a língua que você quer, exemplo: ./configure --with-lang=de. Note que isto funciona apenas se os arquivos base para a tradução em Alemão existirem!

Outra opção para o configure que você pode precisar usar é --with-php=PATH, aonde PATH é o caminho completo para o executável binário do PHP que você quer usar. Na maioria dos casos o binário encontrado do PHP 4 ou PHP 5 automaticamente pelo autoconf estará bem - mas ocasionalmente as pessoas tem configurações estranhas em seus sistema. Você realmente deve usar o CLI para gerar o manual, a propósito, mas geralmente o CGI se arranja.

Você pode previnir as gerações em pedaços (html, phpweb, test) de dizer a você cada vez que eles escrevem um arquivo usando --disable-output. Na teoria ao menos, isto deve tornar a geração mais rapida para estas versões.

Existe uma ultima opção de configuração, --with-history, a qual você pode ou não tropeçar. è usada para definir um caminho a um diretório externo contendo apenas manual/* (um snapshot de php-gtk-doc/manual). Isto é usado apenas para a opção make updates, a qual esta primariamente aqui para gerar a lista de documentação atualizada no servidor. Você não vai precisar dela.

Finalmente, existe uma opção de estilo de saída. Escolher make bigmanual.html irá dar a você um único, grande arquivo HTML em menos de cinco minutos; make text irá fazer o mesmo, mas irá também produzir uma copia do manual como um único arquivo de texto ao final da execução. make html irá eventualmente produzir multiplos arquivos HTML divididos em diretórios em conjunto com uma copia do diretório images; make phpweb irá resultar em uma copia do manual como ele parece no gtk.php.net. Por demanda popular, também existe agora make test id=ID, aonde ID é o id do manual para um componente, ex. tutorials.helloadvanced ou gtk.gtkwindow. Isto irá gerar o arquivo relevante - e qualquer coisa abaixo dele na hierarquia - em um diretório chamado testbuild ao invés de build.

Existem dois tipos de saída que é muito difícil que você vá precisar: make mtoc, o qual cria uma tabela de conteúdo em XML para leitura pelo computador, make updates, o qual é usado no servidor do manual para gerar a lista com as atualizações do manual para a pagina em https://gtk.php.net/.

Outros formatos de saída podem se tornar disponíveis em um futuro proxímo.

A partir da linha de comando, mude para o diretório php-gtk-doc através do comando cd php-gtk-doc. Agora configure alguns arquivos basicos: ./runfirst.sh (ou sh ./runfirst.sh se você esta trabalhando dentro do Windows). O runfirst-script apenas deve ser chamado novamente somente se arquivos completamente novos forem adicionados ao manual, ou se a data de geração preceisa ser atualizada. Assim se você quer compilar o manual em uma base diária, você precisará fazer isso todas as vezes.

Vamos criar o manual em sí: primeiro você deve entender que o manual do php-gtk existe em diversas línguas, em adição aos diversos formatos mencionados anteriormente. Assim ao compilar você precisa qual manual você quer compilar. A língua é determinada como um código de duas letras, como en para Inglês, de para Alemão e assim por diante. O tipo é um de html para a documentação HTML normal que você pode copiar de gtk.php.net, phpweb para gerar os arquivos como a documentação online no site do PHP-GTK, ou test se você quer compilar uma parte dos arquivos apenas.

Assim nós chamamos ./gen_manual.sh <language> <type>, por exemplo ./gen_manual.sh en html. Você verá as linhas fluindo no terminal; vá em algum lugar e volte em dez minutos - levará algum tempo. Os arquivos serão gerados no diretório build/<language>/<type>/, em nosso caso build/en/html/

Se você é um editor e apenas quer testar se a sessão que você recem escreveu esta coreta e aparece como o intencionado no html, você pode chamar ./gen_manual.sh <language> test <id>, como em ./gen_manual.sh en test gtk.gtkiconview. Isto irá ativar um modo especial no qual o manual será reduzido a uma versão minima contento apenas as coisas mais necessárias para compilar esta pagina(id) em especial. Entretanto, este script não é perfeito e pode (atualmente) gerar arquivos de referência, e neste muitos links não funcionam.

Se você tem um servidor Apache com o PHP instalado, você pode usar o livedocs: Abra o arquivo live.php em seu browser (no servidor web, não no diretório local em sí!) e navegue através do manual - as paginas são criadas de acordo com a demanda, na maioria das vezes levando de 1 a 2 segundos.