php-doc-en/chmonly/integration.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <chapter xml:id="chm.integration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Integrating the PHP Manual</title>

  <para>
   <note>
    <para>
     The information provided here is mainly aimed at IDE authors, or
     advanced users who would like to integrate this CHM file to their
     favorite IDEs or other production environment components.
    </para>
   </note>
  </para>
  <para>
   There are several editors out there with support for CHM integration,
   but you may need to know a few things about what the CHM contains
   to successfully integrate the manual into your environment.
  </para>
  <para>
   The CHM is built using XSL style sheets from XML sources. This is
   unique currently in the PHP Manual family, as all other versions are
   generated using DSSSL style sheets. This also means, that
   non-intentional rendering differences may come up. A special
   conversion script is run on the XSLT output, adding several cute
   features, and packing up the manual with the preferences files
   and skin examples.
  </para>
  <para>
   If you never worked with CHMs, you can think of them as compressed
   files with OS supported access for files inside and some added search
   and index support. However CHMs can only be viewed using the HTML Help
   Viewer, you can directly access files inside them using a special URL
   prefix, the CHM file name and the file you request from inside. As all
   the help content is stored in HTML files, you can show pages of the CHM
   in Internet Explorer.
  </para>
  <para>
   Assume that you placed your <filename>php_manual_en.chm</filename> to
   <filename>c:\phpmanual</filename> the index file in the manual (which
   you see the first time) can be accessed with the following URL:
   <literal>mk:@MSITStore:C:\phpmanual\php_manual_en.chm::/_index.html</literal>.
   Here <literal>mk:@MSITStore:</literal> is the special "protocol", 
   <filename>C:\phpmanual\php_manual_en.chm</filename> is the CHM with it's
   full path. The <filename>/_index.html</filename> part is the path to the
   index file inside the CHM and <literal>::</literal> is just what you need
   to put between the CHM path and this file path.
  </para>
  <para>
   <note>
    <para>
     All files are in the root directory of the CHM, unlike the previous
     CHM versions which included a language directory. Images, style sheets
     and other supplemental files have names starting with an underscore
     (like the main index shown above), to avoid name collisions.
    </para>
   </note>
  </para>
  <para>
   The names of generated files follow the same rules as the online
   manual, except that the extension is <literal>.html</literal> and
   not <literal>.php</literal>. The most important is that function
   documentation files are named <filename>function.FUNCNAME.html</filename>
   where <literal>FUNCNAME</literal> is the function name, with all
   underscores converted to hyphens. Some examples are
   <filename>function.echo.html</filename>,
   <filename>function.mysql-close.html</filename>,
   <filename>function.imagecopy.html</filename>.
  </para>
  <para>
   Using all this information, you can show a manual page for a function
   requested by a user. A simple example is included in the distribution,
   named <filename>php_quickref.hta</filename>. This is a
   <link xlink:href="&url.chm.hta;">HTML Application</link> to demonstrate the
   simple process of showing a manual page for a function. The
   <literal>quickRef()</literal> function defined therein does the job.
  </para>
  <para>
   If you would like to integrate the manual into an IDE without direct
   support for the PHP manual (actually the underscore to hyphen conversion),
   you can use the included <filename>_function.html</filename> file to access
   a function page. This file is simply a redirector, and can be parameterized via
   the URL, as <filename>_function.html#mysql_close</filename>. This page
   will redirect you to the mysql_close function page
   (<filename>function.mysql-close.html</filename>) automatically. You can
   provide the full path of this file if your IDE supports context sensitive
   help, and provide the IDE specified string as the parameter. An example
   for this is the UltraEdit 9 intergation (see the edition's website).
  </para>
  <para>
   The index of the manual (accessible via the index tab on the navigation
   pane) can also be used for integrational purposes. All the HTML pages
   are included in the index with their titles as index terms (including
   function description pages).
  </para>
  <para>
   If you are a desktop application developer and would like to tightly
   integrate the CHM into your program (such as displaying the TOC tree
   in your IDE's help box), you can find more information at
   <link xlink:href="&url.chm.helpware;">&url.chm.helpware;</link>, as well as
   links to other useful resources. The official site for HTML Help is
   at <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
-->