archived-doc-pt-br/chmonly/integration.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: leonardolara Status: ready -->
 <chapter xml:id="chm.integration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Integrando o Manual do PHP</title>

  <para>
   <note>
    <para>
     As informações fornecidas aqui destinam-se principalmente a autores de IDE ou
     usuários avançados que desejam integrar este arquivo CHM aos seus
     IDEs favoritos ou outros componentes do ambiente de produção.
    </para>
   </note>
  </para>
  <para>
   Existem vários editores com suporte para integração CHM,
   mas pode ser necessário saber algumas coisas sobre o que o CHM contém
   para integrar o manual com sucesso no ambiente.
  </para>
  <para>
   O CHM é construído usando folhas de estilo XSL de fontes XML. Atualmente,
   isso é único na família do Manual do PHP, já que todas as outras versões são
   geradas usando folhas de estilo DSSSL. Isso também significa que podem
   surgir diferenças de renderização não intencionais. Um script de
   conversão especial é executado na saída XSLT, adicionando vários recursos
   interessantes e empacotando o manual com os arquivos de preferências
   e exemplos de skin.
  </para>
  <para>
   Para quem nunca trabalhou com CHMs, eles podem ser considerados como arquivos compactados
   com acesso compatível com o sistema operacional para arquivos internos e algum suporte
   adicional de pesquisa e índice. No entanto, os CHMs só podem ser visualizados usando o HTML
   Help Viewer. Pode-se acessar diretamente os arquivos dentro deles usando um prefixo de URL
   especial, o nome do arquivo CHM e o arquivo solicitado. Como todo o
   conteúdo da ajuda é armazenado em arquivos HTML, as páginas do CHM podem ser mostradas
   no Internet Explorer.
  </para>
  <para>
   Assumindo que o arquivo <filename>php_manual_pt_BR.chm</filename> está localizado em
   <filename>c:\phpmanual</filename>, o arquivo de índice no manual (que
   é visto no primeiro acesso) pode ser acessado com o seguinte URL:
   <literal>mk:@MSITStore:C:\phpmanual\php_manual_pt_BR.chm::/_index.html</literal>.
   Aqui, <literal>mk:@MSITStore:</literal> é o "protocolo" especial,
   <filename>C:\phpmanual\php_manual_pt_BR.chm</filename> é o arquivo CHM com seu
   caminho completo. A parte <filename>/_index.html</filename> é o caminho para o
   arquivo de índice dentro do CHM e <literal>::</literal> é o que precisa ser
   inserido entre o caminho CHM e este caminho de arquivo.
  </para>
  <para>
   <note>
    <para>
     Todos os arquivos estão no diretório raiz do CHM, ao contrário das versões
     anteriores do CHM que incluíam um diretório de idioma. Imagens, folhas de estilo
     e outros arquivos suplementares têm nomes que começam com sublinhado
     (como o índice principal mostrado acima), para evitar colisões de nomes.
    </para>
   </note>
  </para>
  <para>
   Os nomes dos arquivos gerados seguem as mesmas regras do manual
   online, exceto que a extensão é <literal>.html</literal> e
   não <literal>.php</literal>. O mais importante é que os arquivos
   de documentação da função sejam denominados <filename>function.FUNCNAME.html</filename>
   onde <literal>FUNCNAME</literal> é o nome da função, com todos
   os sublinhados convertidos em hífens. Alguns exemplos são
   <filename>function.echo.html</filename>,
   <filename>function.mysql-close.html</filename> e
   <filename>function.imagecopy.html</filename>.
  </para>
  <para>
   Usando todas essas informações, pode-se mostrar uma página de manual para uma função
   solicitada por um usuário. Um exemplo simples está incluído na distribuição,
   chamado <filename>php_quickref.hta</filename>. Este é um
   <link xlink:href="&url.chm.hta;">aplicativo HTML</link> para demonstrar o
   processo simples de mostrar uma página de manual para uma função. A
   função <literal>quickRef()</literal> definida aqui faz o trabalho.
  </para>
  <para>
   Se a intenção for integrar o manual em um IDE sem suporte direto
   para o manual do PHP (na verdade, a conversão de sublinhado para hífen),
   pode-se usar o arquivo <filename>_function.html</filename> incluído para acessar
   uma página de funções. Este arquivo é simplesmente um redirecionador e pode ser parametrizado através
   da URL, como <filename>_function.html#mysql_close</filename>. Esta página
   irá redirecioná-lo para a página da função mysql_close
   (<filename>function.mysql-close.html</filename>) automaticamente. Pode-se
   fornecer o caminho completo deste arquivo se o IDE suportar ajuda sensível ao
   contexto e fornecer a string especificada do IDE como parâmetro. Um exemplo
   disso é a integração UltraEdit 9 (veja o site de edição).
  </para>
  <para>
   O índice do manual (acessível através da guia índice no painel de
   navegação) também pode ser usado para fins de integração. Todas as páginas HTML
   são incluídas no índice com seus títulos como termos de índice (incluindo
   páginas de descrição de funções).
  </para>
  <para>
   No caso de desenvolvedores de aplicações aotônomas que gostariam de integrar totalmente
   o CHM à aplicação (como exibir a árvore de Tabela de Conteúdo
   na caixa de ajuda do IDE), mais informação pode ser encontrada em
   <link xlink:href="&url.chm.helpware;">&url.chm.helpware;</link>, bem como
   atalhos para outros recursos úteis. A página oficial da Ajuda HTML está em
   <link xlink:href="&url.chm;">&url.chm;</link>.
  </para>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->