Vou mostrar um pouco do manual do PHP, como se trabalha nele, e como são gerados os vários formatos que existem dele. Também uma descrição da sua estrutura interna.

Ao contrário do que as pessoas pensam, o manual não é escrito em HTML. Ele é escrito em XML ( variação com regras mais rígidas do html), usando o docbook, que é um formato bastante conhecido para livros e documenação. Esta dividido em muitos arquivos, normalmente cada um representa uma função ou um capitulo.

A utilização de XML permite que o manual seja convertido para vários formatos, isso é necessário, pois temos um formato para apresentação no site e outros para que você possa copiar para ler em seu computador, como o HTML em um único arquivo e o  HTML em vários arquivos(recomendo este). Antigamente existiam para download outros formatos, como o PDF, o RTF(usado em editor de texto, como o wordpad e outros mais complexos como MS Word e OpenOffice) e um arquivo de texto puro. Com o tempo houveram mudanças na estrutura do manual e nas ferramentas utilizadas, e não houve interesse mais em manter estes formatos, ou então dificuldades tecnicas que ninguem se preocupou em resolver.

Atualmente o manual do PHP é composto de mais de 6.000 arquivos. Ele cobre as extenções oficiais do PHP(aquelas que são distribuídas com ele), a parte de como criar um módulo do PHP(isso é, adicionar funções e classes ao próprio código fonte do php, isso é escrito em c/c++), embora esta parte esteja bastante desatualizada. Cobre também os módulos do PECL, que é um repositório para várias extenções não oficiais do PHP. Quando uma extensão se torna estável o suficiente ela as vezes passa para o php, e quando esta no PHP e se torna obsoleta, passa para o PECL(estas mudnças dependem de outros fatores também, como ter o interesse de desenvolvedores em mante-la e não ter um uso especifico demais). A documentação das extenções PECL esta em processo de migração, então uma parte já esta no manual do PHP, uma parte no manual do PEAR e outra solta. O objetivo é passar a documentação do PECL para o PHP.

Com o tempo o PHP tem ganho novas funções/classes e isso tem feito o manual crescer. Como comparação, quando eu comecei a participar eram cerca de 3.000 arquivos, mas hoje já passam de 6.000 arquivos. Durante este tempo houveram algumas modificações na própria estrutura do manual.

Antigamente cada módulo, por exemplo todas as funções do MySQL estavam em um só arquivo, conforme a documentação foi ficando mais complexa, os arquivos cresceram, e isso foi criando arquivos muito grandes, ruim para se trabalhar. Se optou então por fazer uma pagina de referencia e uma com cada função. Se hoje ainda estivessem juntos teriamos com certesa vários arquivos com mais de 5.000 linhas.

Atualmente esta em processo uma outra separação, a divisão das referencias em outros arquivos menores. Isso também trará benefícios, como uma maior facilidade para traduzir/atualizar. Mas tem como motivos principais uma nova apresentaçã e a possibilidade de gerar a documentação de cada extenção de forma separada. A única questão contra isso é que gera mais trabalho para a tradução, pois teremos que atualizar isso.

Falei antes que o manual é escrito em XML. Há muito tempo ele era convertido usando o openjade, usando DSSSL. Esse metodo é bom, mas tem algumas desvantagens, como a dificuldade emmanter o sistema funcionando quando era necessária qualquer mudança. Além disso, tinha a demora em gerar o manual. no servidor oficial, que gera o manual em todos os formatos e línguas, esse tempo de gerar o manual chegou a passar de um dia para cada língua.

Claro que existia a necessidade de se gerar o manual de uma maneira mais rápida. Se optou por usar XSL, e usar o xstlproc para isso. Dimunuiu em muito o tempo necessário, para mim aqui em casa, diminuiu para cerca de um terço do tempo. Essa mudança trouxe um pouco de trabalho para a tradução, mas a economia de tempo em gerar o manual conpensou isso. As mudanças necessárias foram a alteração de algumas marcações e a necessidade de tornar o xml realmente válido.

Mas esse sistema tinha ainda alguns problemas, por exemplo, quando voce alterava um arquivo, você tinha que recompilar todo o manual para testar as novas mudanças. Foi planejado então um novo sistema, chamado livedocs, que resolveria esta questão. Primeiro era necessária a criação de um índice, que nao era muito mais rapido do que criar o manual com o xsltproc. Mas a grande vantagem dele é que os arquivos eram convertidos em tempo real de acordo com o que você quisesse ver, mas você tinha que ter um servidor apache funcionando. Devido a diversos problemas que foram surgindo e a falta de como resolve-los esse projeto foi abandonado. Embora ele tenha gerado ons frutos, ele precisava ser repensado, ser refeito do início. Uma pena.

Eis que um tempo depois disso surge um novo projeto. Com algumas idéias do livedocs, como usar o PHP para criar a documentação, mas gerar ela por inteiro, e não sobre demanda. O nome deste projeto é PHP's DocBook Rendering System (mais conhecido como PhD). Ele tem apresentado otimos resultados. sinceramente a primeira vez que fiz eu achei que tinha dado errado, porque tinha sido rapido de mais, sério, mas fui ver os arquivos realmente estavam lá. Fez todo o maual em menos de três minutos, maravilha!