goba Sun Aug 11 13:21:03 2002 EDT
Added files:
/phpdoc/en/chmonly integration.xml
Log:
Adding IDE integration information (actually details on the contents
of the CHM)
Index: phpdoc/en/chmonly/integration.xml
+++ phpdoc/en/chmonly/integration.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<chapter id="chm.integration">
<title>Integrating the PHP Manaul</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 colissions.
</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
<ulink url="&url.chm.hta;">HTML Application</ulink> 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>
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
<ulink url="&url.chm.helpware;">&url.chm.helpware;</ulink>, as well as
links to other useful resources. The official site for HTML Help is
at <ulink url="&url.chm;">&url.chm;</ulink>.
</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:"../../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
-->
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
