1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<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
-->
|
