goba Mon Aug 12 08:42:31 2002 EDT
Added files:
/phpdoc/en/chmonly skins.xml specialities.xml
Log:
Adding information on preferences, example coloring and the first
part of the skin development chapter (more to come on that part).
Index: phpdoc/en/chmonly/skins.xml
+++ phpdoc/en/chmonly/skins.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<chapter id="chm.skins">
<title>Skin development</title>
<para>
This edition of the PHP Manual allows users to choose from skins to
display the contents, as well as develop custom skins to meet some
special needs. We decided to support skins because we realized that
one skin cannot satisfy everybodies needs in a such heavily used
edition.
</para>
<para>
We included two skins by default inside the CHM. These cannot be modified
or removed, so if you have the CHM, you have these two skins inside. The
Low skin is optimized for small window display, the High skin is a
variation of the Low one with some graphics added to spice it up.
</para>
<para>
A skin must have at least two files, a skin loader JavaScript file and
a CSS file. The two inline skins have thes files inside the CHM. The
skin loader JS should at least load in the CSS file and display the
page contents to the viewer. Theoretically there are two kinds of skins:
CSS skins and Full skins. CSS skins only modify the CSS and does not
amend the page layout. Full skins also modify the page layout. We have
included sample skins for both the CSS skin type and the Full skin type.
</para>
<sect1 id="chm.skins.display">
<title>Page Display Process</title>
<para>
If you are going to develop your own skin, you should now how one
page is loaded and displayed to the user, and how a skin fits in
this process. For these paragraphs, we assume that you have put
your CHM into <filename>c:\phpmanual</filename>, so it's accessible
as <filename>c:\phpmanual\php_manual_LANG.chm</filename> (where LANG
is the language code), and you would like to see the function page
of "echo", which is <filename>function.echo.html</filename> inside
the CHM. See the <link linkend="chm.integration">sections about
integration</link> for more information on CHM contents.
<itemizedlist>
<listitem>
<simpara>
First of all the HTML content is loaded in from
<filename>function.echo.html</filename>.
</simpara>
</listitem>
<listitem>
<simpara>
At the top of this file, there is a HTML <script> tag, which
loads in the <filename>_script.js</filename> file from the CHM. This
file contains all the JS code needed to move on with the process.
Most importantly this JS defines many variables (like where the CHM
is, or what is the actual page viewed) and many functions to print
out the context menu or handle online functions.
</simpara>
</listitem>
<listitem>
<simpara>
At last <filename>_script.js</filename> loads in the preferences
file from outside the CHM (in <filename>c:\phpmanual</filename> in
our example). This JS file defines the preference variables, and
calls back <literal>prefHandler()</literal> which is also defined in
<filename>_script.js</filename>.
</simpara>
</listitem>
<listitem>
<simpara>
That function loads in the skin JS file as the preferences
dictate. The sknin JS file should load in the needed CSS
file, and define a <literal>displayPage()</literal> function,
which displays the page if called.
</simpara>
</listitem>
<listitem>
<simpara>
The HTML file (<filename>function.echo.html</filename> in this
example) also contains a function call to load in the user notes,
which simply puts the notes into this HTML file using DHTML to
be displayed as if they were here before...
</simpara>
</listitem>
<listitem>
<simpara>
The HTML file also contains a body onload attribute which
calls the skin-defined <literal>displayPage()</literal> function
to show the page to the user. This is the last function called,
it should present the page in it's complete form to the user.
</simpara>
</listitem>
</itemizedlist>
Every action is syncronized with calling back a function in
the previously loaded file when the JS is in memory. The notes
loading and skin JS loading is only syncronized with the page's
onload event (which as the Microsoft documentation says only fires
if the page is completely loaded).
</para>
<para>
This load and callback chain may seem to be too complicated, but
so far this seemed to be the best way to do as many things as
possible paralelly, while also syncronize some calls.
</para>
<para>
As you can see your skin JavaScript file is loaded in by
<filename>_script.js</filename> and it's <function>displayPage()</function>
function is called by the body onload event.
</para>
</sect1>
</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
-->
Index: phpdoc/en/chmonly/specialities.xml
+++ phpdoc/en/chmonly/specialities.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<chapter id="chm.specialities">
<title>Specialities of this Edition</title>
<para>
The Windows HTML Help Edition of the PHP Manual overperforms the
presentational and interactive capabilities offered by other editions
(including the online manual). This was possible because currently CHMs
can only be viewed on Windows using Internet explorer, so we can develop
for one browser family and one operating system. Viewers for other OSes
may be developed in the future by third parties.
</para>
<sect1 id="chm.specialities.prefs">
<title>User Preferences</title>
<para>
Most of the interactive features of this manual are provided by the
viewer application (including full text search, index, favorites
list), but we extended this list with PHP Manual specific tools.
All these can be adjusted to your needs using a simple desktop
application named <filename>php_manual_prefs.exe</filename>. If you
run this program you can see three groups of settings: Online Functions,
Context Menu, and Skin. All your settings are stored in
<filename>php_manual_prefs.js</filename>.
</para>
<para>
Online functions enable you to have elements connected to websites.
The two ones you can see on all manual pages are "This page online"
and "Report a bug". As you can figure out the first one shows you
the same page in the online manual, the second one opens a page
from <ulink url="&url.php.bugs;">&url.php.bugs;</ulink> and prefills
some bug data for you. You need to select a mirror site to use for
"php.net sensitive" online functions. We recommend choosing a close
mirror site to get the best speed. Other components that may be
limited by this online functions setting include context menu items
opening new websites ("Google search selection" for example).
Custom designs may also include elements restricted by this setting.
</para>
<para>
The context menu settings enables you to override the system default
context menu provided by the HTML Help Viewer and define your own
by selecting from a list of predefined menu elements. Three special
types of context menu items exist:
<table>
<title>Context menu items</title>
<tgroup cols="3">
<thead>
<row>
<entry>Type</entry>
<entry>Examples</entry>
<entry>Comments</entry>
</row>
</thead>
<tbody>
<row>
<entry>Page Jump</entry>
<entry>Function Reference, Function Index</entry>
<entry>
These items jump to a specific page in the CHM. Page Jump options are not
restricted to point inside the CHM though. They can point to websites or
other resources. Page jump options with a protocol part in the URL open
in new window.
</entry>
</row>
<row>
<entry>Function Call</entry>
<entry>Print page, Select all, Copy selection to clipboard, Google Search
Selection</entry>
<entry>
These are "function calls" for internally defined context
menu functions. The last two examples have the speciality that they
only show up in the menu if you rightclicked on a selection.
Currently there is no way to extend the context menu with skin
defined functions.
</entry>
</row>
<row>
<entry>Special display</entry>
<entry>Google SearchBox, AlltheWeb SearchBox</entry>
<entry>
These are displayed as HTML forms, where you can enter search
keywords, press ENTER, and receive a new window with the search
issued in the appropriate search engine. Currently there is no
way to extend specialy displayed context menu items.
</entry>
</row>
</tbody>
</tgroup>
</table>
Possible context menu elements and their "abstract implementations" are
stored in <filename>context.ini</filename>. You have the ability to add
possible page jump options there, but there is no way currently to extend
the context menu system with user (skin) defined functions. The possible
mirror sites are listed in <filename>mirrors.ini</filename>. Feel free to
suggest more bundled context menu items to us at
<ulink url="mailto:&email.php.doc.chm;";>&email.php.doc.chm;</ulink>.
</para>
<para>
The skins setting enables you to choose from the two bundled default
skins, or from any user defined skins. The Low skin is optimized to
display correctly at any small size, the High skin is optimized for
your viewing pleasure. Other skins may be developed according to our
skins development guide. The recommended place for skins on the file
system is the <filename>skins/SKINNAME</filename> subfolder of the PHP
Manual directory. Though this is not required, some skins may define
other rules (not recommended). We included sample skins for you to
see examples of how to develop skins for the PHP Manual.
</para>
<para>
You have three buttons to choose from at the bottom. The Apply button
applies your changes without exiting, the OK button applies and closes
the application, the Cancel button does not modify your settings and
closes the program.
</para>
</sect1>
<sect1 id="chm.specialities.presentation">
<title>Presentational Specialities</title>
<para>
This edition of the PHP Manual is highly optimized for screen
presentation. Skins may be developed to better support printing,
as this was not the goal of the included skins. This approach
allowed us to make many modifications to the presentation of
different parts of the manual.
</para>
<para>
The first thing you'll notice is that all examples are color coded,
using the PHP function <function>show_source</function>. The actual
colors used are defined by CSS classes. Examples also have links to
PHP functions used in them to provide quick access to reference
material. All code examples have a "copy to clipboard" link by the
side of them with which you can copy the text contents of the example
to the clipboard.
</para>
<para>
External links are marked with a special » sign, and open in
a new browser window. We also included the "path to this page"
information on all pages for you to easily identify where you are
and navigate as needed.
</para>
<para>
Other parts of the manual are quite similar to the online ones by
default, though custom skins can modify many elements on the pages.
</para>
</sect1>
</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
