Este capitulo lida atualmente em contribuir om a documentação do PHP-GTK 2. Se você tiver alguma questão posterior, sinta-se a vontade para pergunta-la na lista de email do php-gtk-doc.
Se você escreveu alguma documentação, você provavelvente vá querer que ela vá no manual oficial. Por favor envie os seus arquivos por email para a lista de email do php-gtk-doc mencionada acima, ou para um dos contribuidores listados na pagina dos créditos da documetação. Esles irão colocar o seu trabalho nos fontes oficiais no servidor CVS. Se você contribuir regularmente para a documentação, você pode obter uma conta de CVS. Pergunte sobre isto na lista de email da documentação.
Se você tem uma conta de CVS: SEMPRE compile o manual antes de enviar as suas modificações! Se houver um erro no xml, a geração noturna do manual irá parar e as pessoas irão reclamar.
Os fontes do manual consistem de mais de 300 arquivos únicos, e assim são altas as chances que ajam pontos em branco na documentação. Se você já tiver visto o que esta faltando ao navegar pelo manual, vá em frente e prencha o ponto em branco que mais lhe interessar. Se você não souber de nenhum lugar, procure nos arquivos do manual por comentários FIXME e TODO e começe por aqui.
Como você já deve ter visto, as fontes do manual estão no diretório manual/, o qual contém pastas para cada língua. De uma olhada em manual/en/reference/ - você encontrará pastas para gtk, gdk. Cada classe tem o seu próprio arquivo xml em uma das pastas - isto permite a várias pessoas trabalharem em partes diferentes do manual ao mesmo tempo, e permite a maquinas mais lentas abrir o arquivo do manual.
Você provavelmente não irá precisar adicionar quaiquer arquivos, porque os esqueletos para a documentação das classes devem existir no mínimo. Se você tiver que adicionar um novo arquivo, tenha certesa de registra-lo em manual/reference.xml - se não ele não será incluído no manual.
Imagens de classes tem o seu próprio diretório, images/. A estrutura do diretório é a mesma que aquela para os arquivos xml; poe xemplo, a imagem para GtkAboutDialog esta em images/reference/gtk/gtkaboutdialog.png. Se você criar novas imagens, tenha certesa que seja pequena. Um arquivo com 30kb é muito grande, se você adicionar o tamanho de todas as imagens. Também tenha certesa de usar arquivos .png, e reduza a paleta para um tamanho fixo para manter o tamanho do arquivo pequeno.
Exemplos executáveis tem o seu próprio diretório examples/ com uma estrutura similar aos aquivos de imagem e xml, com a exeção que cada classe tem o seu próprio diretório. Os arquivos são chamados com o nome da função/método da qual eles dão exemplo, para a função: set_logo() da classe GtkAboutDialog deve ir em examples/reference/gtk/gtkaboutdialog/set_logo.phpw. Note a extensão do arquivo. O nome do arquivo do construtor padrão é constructor.phpw.
Primeiro uma palavra: Escreva a documentação com qualquer progrma que você queira. Eu prefiro o editor de texto do KDE Kate, mas um vi, emacs ou até mesmo Notepad irão fazer o trabalho. Nota: Se você usar caracteres que não sejam ASCII, você precisa salvar o arquivo como UTF-8.
A documentação consiste de texto estruturado: Você diz que um texto esta em um paragrafo, que a palavra deve ter uma enfâse especial ou que outra palavra deve ser entendida como literal. Se você escreveu paginas em HTML, você já saberá o conceito.
Você deve imaginar porque a documentação não usa tags HTML: è porque o DocBook apenas descreve a estrutura do texto, ele não formata-o. O HTML tenta separar o layout (CSS) e o conteúdo (XHTML) também, mas o DocBook pode ser usado para produzir não apenas HTML, mas PDF e livros reais também. Existem vários elementos especiais em um livro: Capítulos, sessões, exemplos, e em um manual de programação como este você tem métodos, parâmetros, propriedades, sinais e assim por diante. Cada eleento tem a sua própria tag. Isto parece confuso quando você começa com o DocBook, mas tem seus benefícios: Controle completo sobre a saída.
O mais básico elemento é <para>, usado para separar o texto emparagrafos. Paragrafos contém outras tags como links, nomes de arquivos, tabelas e assim por diante. Existe um tipo de paragrafo especial <simpara> para paragrafos que não contenham nenhuma outra tag.
As próximas tags importantes são os links. De uma olhada na sua sessão.
Você pode colocar enfâse em palavras ou grupos de palavras através <emphasis>, ou definir literais com <literal>. Nomes de arquivo podem ser expressados com <filename>, variáveis com <varname>. Existem muitas mais pequenas tags, mas lista-las aqui faria uma manual inteiro.
Se você quer listar itens, use as tags <itemizedlist> (não ordenado) ou <orderedlist> (ordenado). Os item da lista nela devem ser cercados com uma tag <listitem>.
<listitem>s em sí podem conter <para> e outras tags.Na maioria das vezes o esqueleto da documentação da classe existe, e você irá apenas ter que prencher a descrição com o conteúdo e as tags mencionadas acima. As tags que precisam ser prenchidas são: <shortdesc> para uma descrição curta da classe/função/sinal/propriedade (apenas um único paragrafo, preferencialmente sem tags nele) e <desc> com uma descrição completa da classe (use vários paragrafos).
Se você não tem certesa como fazer algo ou se a tag que você escolheu esta correta, de uma olhada nos outros arquivos já escritos - eles são o melhor exemplo.
O manual vive através de links que interconectam as paginas, permitindo pular para outra sessão importante com um click. Sempre que você fazer uma referencia para outra classe ou um função similar, crie um link. Ele salva tempo das pessoas procurarem.
O manual conhece quatro tipos de links entre as paginas:
Links de Classe cria um link para a pagina da descrição de uma certa classe. Porr exemplo, você usaria:
Para criar um link para a descrição da classe GtkAboutDialog. Ele irá parecer com isto: GtkAboutDialog.Links para metodos/funções conectam a um metodo ou função de uma certa classe. O nome da função irá automaticamente ser completado com (). Use
para realizar esta tarefa. O manual irá mostrar: set_logo() . O parâmetro class não é necessário se você criar uma ligação para a classe atual; mas adicione-o mesmo assim - significa menos esforço ao copiar alguma coisa para uma parte diferente do manual.Links para sinais são criados desta maneira:
Isto será compilado como: "close".Links para enumerações também são muito simples:
Isto irá resultar em: GtkButtonBoxStyle. Você pode também criar um link para uma enumeração ou flag usando o seu campo de opção: Isto irá compilar em: Gtk::ICON_LOOKUP_FORCE_SVG.Links de Propriedade são simples:
Isto irá resultar em: action_area.Links livres do manual são necessários se você quer criar um link para uma certa palavra de texto, ou para uma sessão do tutorial. Você precisa prover o ID da sessão que ocê quer criar o link, e é libre para escolher um titulo:
Veja o resultado: The documentation tutorial shows you how to compile the manual.The <link linkend="tutorials.doccing">documentation tutorial</link> shows you how to compile the manual.
Links para URL deixa o escopo do manual; você pode escrever links para qualquer endereço de HTTP, FTP ou email que você quiser:
o qual vai se parecer com: lista de email da documentação. Se um link é comunmente usado no manual, você pode usar uma das várias entidades XML listadas em manual/global.ents para ter um efeito similar: o qual resultará em: [email protected], e o qual dará a você: lista de email da documentação.<ulink url="mailto:[email protected]">lista de email da documentação</ulink>
A documentação do PHP-GTK 2, diferentemente da versão criada para o PHP-GTK 1, suporta imagens e exemplos de códigos externos.
Existem três tipos de imagens: imagens de classe, imagens normais as quais craim seu próprio paragrafo, e imagens internas as quais fluem com o texto.
Imagens de Classe são exibidas na pagina da descrição da classe, do lado direito da descrição. Apenas adicione
Note que o diretório base &directory.images;; ele será substituido com o diretório correto das imagens na hora de compilar.Imagens normais são incluídas no paragrafo através de
e imagens internas comExemplos de código podem ser separados do arquivo do manual também. isot é especialmente útil para leitores que querem usar o exemplo por sí mesmos: sem a necessidade de copiar e colar o código, apenas execute-o no diretório de exemplos de códigos. Alem disso, é mais fácil para testar os exemplos ao escrever e editar o manual.
Exemplos devem ter o seu prórpio arquivo apenas se eels forem um programa completo, executável - pedaços de códgo devem ser embutidos.
Exemplos separados em arquivos podem ser inclusos desta maneira:
<example>
<title>Simple GtkAboutDialog</title>
<programlisting role="php">
<xi:include xmlns:xi="https://www.w3.org/2001/XInclude"
href="../&directory.examples;/reference/gtk/gtkaboutdialog/constructor.phpw"
parse="text">
<xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
</xi:include>
</programlisting>
</example>
|
Exemplos para pedaços de código devem ser embutidos assim:
<informalexample>
<programlisting role="php"><![CDATA[
//some php code here
]]></programlisting>
</informalexample>
|