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 &lt;script&gt; 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 &raquo; 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

Reply via email to