goba Mon Jul 22 09:12:37 2002 EDT
Added files:
/phpdoc/en/reference/hw constants.xml
Modified files:
/phpdoc/en/reference/hw reference.xml
/phpdoc/en/reference/hwapi reference.xml
Log:
. HW and HWAPI new structure applied
. Interlinking the two extensions
. Adding more tags to HW documentation
. Standardizing IDs
. Adding constants to HW docs
Index: phpdoc/en/reference/hw/reference.xml
diff -u phpdoc/en/reference/hw/reference.xml:1.2
phpdoc/en/reference/hw/reference.xml:1.3
--- phpdoc/en/reference/hw/reference.xml:1.2 Mon Apr 15 14:56:40 2002
+++ phpdoc/en/reference/hw/reference.xml Mon Jul 22 09:12:33 2002
@@ -1,24 +1,28 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<reference id="ref.hyperwave">
<title>Hyperwave functions</title>
<titleabbrev>Hyperwave</titleabbrev>
<partintro>
- <section id="hw-intro">
- <title>Introduction</title>
+ <section id="hyperwave.intro">
+ &reftitle.intro;
<para>
- <productname>Hyperwave</productname> has been developed at <ulink
url="&url.iicm;">IICM</ulink> in Graz. It started with
+ <productname>Hyperwave</productname> has been developed at
+ <ulink url="&url.iicm;">IICM</ulink> in Graz. It started with
the name <acronym>Hyper-G</acronym> and changed to Hyperwave when
- it was commercialised (If I remember properly it was in 1996).
+ it was commercialised (in 1996).
</para>
<para>
- Hyperwave is not free software. The current version, 4.1, is
- available at <ulink url="&url.hyperwave;">www.hyperwave.com</ulink>.
+ Hyperwave is not free software. The current version, 5.5 is
+ available at <ulink url="&url.hyperwave;">&url.hyperwave;</ulink>.
A time limited version can be ordered for free (30 days).
</para>
<para>
+ See also the <link linkend="ref.hwapi">Hyperwave API</link> module.
+ </para>
+ <para>
Hyperwave is an information system similar to a database
(<acronym>HIS</acronym>, Hyperwave Information Server). Its focus
is the storage and management of documents. A document can be any
@@ -34,17 +38,17 @@
This makes sense if you want to specify a title in several languages.
In such a case there is a convention, that each title value is
preceded by the two letter language abbreviation followed by a colon,
- e.g. 'en:Title in English' or 'ge:Titel in deutsch'. Other attributes
- like a description or keywords are potential candidates. You may
- also replace the language abbreviation by any other string as long
- as it separated by colon from the rest of the attribute value.
+ e.g. <literal>'en:Title in English'</literal> or <literal>'ge:Titel
+ in deutsch'</literal>. Other attributes like a description or keywords
+ are potential candidates. You may also replace the language
+ abbreviation by any other string as long as it separated by colon
+ from the rest of the attribute value.
</para>
<para>
Each object record has native a string representation with each
- name/value
- pair separated by a newline. The Hyperwave extension also knows
- a second representation which is an associated array with the
- attribute name being the key. Multilingual attribute values itself
+ name/value pair separated by a newline. The Hyperwave extension
+ also knows a second representation which is an associated array with
+ the attribute name being the key. Multilingual attribute values itself
form another associated array with the key being the language
abbreviation. Actually any multiple attribute forms an associated
array with the string left to the colon in the attribute value
@@ -60,7 +64,7 @@
about where it starts and where it ends.
In order to gain the original document you will have
to retrieve the plain document without the links and the list
- of links and reinsert them (The functions
+ of links and reinsert them. The functions
<function>hw_pipedocument</function> and <function>hw_gettext</function>
do this for you. The advantage of separating links
from the document is obvious. Once a document to which a link
@@ -81,33 +85,32 @@
The fundamental difference between Hyperwave and the web is the clear
distinction between names and hierarchy in Hyperwave. The name does
not contain any information about the objects position in the hierarchy.
- In the web the
- name also contains the information on where the object is located
- in the hierarchy. This leads to two possibles ways of mapping. Either
- the Hyperwave hierarchy and name of the Hyperwave object is reflected
- in the URL or the name only.
- To make things simple the second approach is used.
- Hyperwave object with name 'my_object' is mapped to
- 'http://host/my_object' disregarding where it resides in the
- Hyperwave hierarchy.
- An object with name 'parent/my_object' could be the child of
- 'my_object' in the Hyperwave hierarchy, though in a web namespace it
- appears to be just the opposite and the user might get confused.
- This can only be prevented by selecting reasonable object names.
+ In the web the name also contains the information on where the object
+ is located in the hierarchy. This leads to two possibles ways of mapping.
+ Either the Hyperwave hierarchy and name of the Hyperwave object is
+ reflected in the URL or the name only. To make things simple the second
+ approach is used. Hyperwave object with name <literal>my_object</literal>
+ is mapped to <literal>http://host/my_object</literal> disregarding where
+ it resides in the Hyperwave hierarchy. An object with name
+ <literal>parent/my_object</literal> could be the child of
+ <literal>my_object</literal> in the Hyperwave hierarchy, though in a web
+ namespace it appears to be just the opposite and the user might get
+ confused. This can only be prevented by selecting reasonable object names.
</para>
<para>
Having made this decision a second problem arises. How do you
- involve PHP? The URL http://host/my_object will not call any
- PHP script unless you tell your web server to rewrite it to
- e.g. 'http://host/php3_script/my_object' and the script 'php3_script'
- evaluates the $PATH_INFO variable and retrieves the object with
- name 'my_object' from the Hyperwave server. Their is just one little
+ involve PHP? The URL <literal>http://host/my_object</literal> will
+ not call any PHP script unless you tell your web server to rewrite it to
+ e.g. <literal>http://host/php_script/my_object</literal> and the script
+ <literal>php_script</literal> evaluates the <varname>$PATH_INFO</varname>
+ variable and retrieves the object with name <literal>my_object</literal>
+ from the Hyperwave server. Their is just one little
drawback which can be fixed easily. Rewriting any URL would not allow
any access to other document on the web server. A PHP script for
searching in the Hyperwave server would be impossible. Therefore
you will need at least a second rewriting rule to exclude certain
- URLS like all e.g. starting with http://host/Hyperwave. This is
- basically sharing of a namespace by the web and Hyperwave server.
+ URLs like all e.g. starting with <literal>http://host/Hyperwave</literal>
+ This is basically sharing of a namespace by the web and Hyperwave server.
</para>
<para>
Based on the above mechanism links are insert into documents.
@@ -119,19 +122,19 @@
retain the Hyperwave hierarchy and map in onto the file system. This
conflicts with the object names if they reflect its own hierarchy
(e.g. by choosing names including '/'). Therefore '/' has to be
- replaced by another character, e.g. '_'. to be continued.
+ replaced by another character, e.g. '_'.
</para>
<para>
The network protocol to communicate with the Hyperwave server is called
<ulink url="&spec.hyperwave;">HG-CSP</ulink> (Hyper-G Client/Server
Protocol). It is based on messages to initiate certain actions, e.g. get
- object record. In early versions of the Hyperwave Server two native
+ object record. In early versions of the Hyperwave Server two native
clients (Harmony, Amadeus) were provided for communication with the
- server. Those two disappeared when Hyperwave was commercialised. As a
+ server. Those two disappeared when Hyperwave was commercialised. As a
replacement a so called wavemaster was provided. The wavemaster is like a
protocol converter from <abbrev>HTTP</abbrev> to <abbrev>HG-CSP</abbrev>.
The idea is to do all the administration of the database and
- visualisation of documents by a web interface. The wavemaster implements
+ visualisation of documents by a web interface. The wavemaster implements
a set of placeholders for certain actions to customise the interface.
This set of placeholders is called the <abbrev>PLACE</abbrev> Language.
<abbrev>PLACE</abbrev> lacks a lot of features of a real programming
@@ -141,10 +144,10 @@
</para>
<para>
Adding Hyperwave support to PHP should fill in the gap of a
- missing programming language for interface customisation. It
- implements all the messages as defined by the
- <abbrev>HG-CSP</abbrev> but also provides more powerful commands
- to e.g. retrieve complete documents.
+ missing programming language for interface customisation. It
+ implements all the messages as defined by the <abbrev>HG-CSP</abbrev>
+ but also provides more powerful commands to e.g. retrieve complete
+ documents.
</para>
<para>
Hyperwave has its own terminology to name certain pieces of
@@ -166,26 +169,26 @@
attribute=value. The pairs are separated by a carriage return
from each other. An object record can easily be converted into
an object array with <function>hw_object2array</function>.
- Several functions return object records. The names of those
+ Several functions return object records. The names of those
functions end with obj.
</simpara>
</listitem>
<listitem>
<simpara>
- object array: An associated array with all attributes of an
- object. The key is the attribute name. If an attribute occurs
+ object array: An associative array with all attributes of an
+ object. The keys are the attribute names. If an attribute occurs
more than once in an object record it will result in another
- indexed or associated array. Attributes which are language
+ indexed or associative array. Attributes which are language
depended (like the title, keyword, description) will form an
- associated array with the key set to the language
- abbreviation. All other multiple attributes will form an
+ associative array with the keys set to the language
+ abbreviations. All other multiple attributes will form an
indexed array. PHP functions never return object arrays.
</simpara>
</listitem>
<listitem>
<simpara>
hw_document: This is a complete new data type which holds the
- actual document, e.g. HTML, PDF etc. It is somewhat optimised
+ actual document, e.g. HTML, PDF etc. It is somewhat optimized
for HTML documents but may be used for any format.
</simpara>
</listitem>
@@ -193,7 +196,7 @@
</para>
<para>
Several functions which return an array of object records do also
- return an associated array with statistical information about
+ return an associative array with statistical information about
them. The array is the last element of the object record
array. The statistical array contains the following entries:
<variablelist>
@@ -254,7 +257,21 @@
</para>
</section>
- <section id="hw-apache">
+ <section id="hyperwave.requirements">
+ &reftitle.required;
+ <para>
+ This extension needs a Hyperwave server downloadable
+ from <ulink url="&url.hyperwave;">&url.hyperwave;</ulink>.
+ </para>
+ </section>
+
+ <section id="hyperwave.installation">
+ &reftitle.install;
+ <para>
+ </para>
+ </section>
+
+ <section id="hyperwave.apache">
<title>Integration with Apache</title>
<para>
The Hyperwave extension is best used when PHP is compiled as an
@@ -264,23 +281,23 @@
</para>
<para>
Since PHP with Hyperwave support built into Apache is intended
- to replace the native Hyperwave solution based on Wavemaster I
+ to replace the native Hyperwave solution based on Wavemaster, we
will assume that the Apache server will only serve as a Hyperwave
- web interface. This is not necessary but it simplifies the
- configuration. The concept is quite simple. First of all you
- need a PHP script which evaluates the <envar>PATH_INFO</envar>
+ web interface for these examples. This is not necessary but it simplifies
+ the configuration. The concept is quite simple. First of all you
+ need a PHP script which evaluates the <varname>$_ENV['PATH_INFO']</varname>
variable and treats its value as the name of a Hyperwave
- object. Let's call this script 'Hyperwave'. The URL
- <systemitem role="url">http://your.hostname/Hyperwave/name_of_object</systemitem>
+ object. Let's call this script <literal>'Hyperwave'</literal>. The URL
+ <literal>http://your.hostname/Hyperwave/name_of_object</literal>
would than return the Hyperwave object with the name
- 'name_of_object'. Depending on the type of the object the script
- has to react accordingly. If it is a collection, it will probably
+ <literal>'name_of_object'</literal>. Depending on the type of the object
+ the script has to react accordingly. If it is a collection, it will probably
return a list of children. If it is a document it will return the
mime type and the content. A slight improvement can be achieved
- if the Apache rewriting engine is used. From the users point of
+ if the Apache rewriting engine is used. From the users point of
view it would be more straight forward if the URL
- <systemitem role="url">http://your.hostname/name_of_object</systemitem> would
- return the object. The rewriting rule is quite easy:
+ <literal>http://your.hostname/name_of_object</literal> would
+ return the object. The rewriting rule is quite easy:
<informalexample>
<programlisting role="apache-conf">
@@ -293,7 +310,7 @@
Now every URL relates to an object in the Hyperwave server. This
causes a simple to solve problem. There is no way to execute a
different script, e.g. for searching, than the 'Hyperwave'
- script. This can be fixed with another rewriting rule like the
+ script. This can be fixed with another rewriting rule like the
following:
<informalexample>
@@ -304,14 +321,14 @@
</programlisting>
</informalexample>
- This will reserve the directory <filename
class="directory">/usr/local/apache/htdocs/hw</filename> for
- additional scripts and other files. Just make sure this rule is
+ This will reserve the directory <filename>/usr/local/apache/htdocs/hw</filename>
+ for additional scripts and other files. Just make sure this rule is
evaluated before the one above. There is just a little drawback:
- all Hyperwave objects whose name starts with 'hw/' will be
- shadowed. So, make sure you don't use such names. If you need
+ all Hyperwave objects whose name starts with <literal>'hw/'</literal>
+ will be shadowed. So, make sure you don't use such names. If you need
more directories, e.g. for images just add more rules or place
- them all in one directory. Finally, don't forget to turn on the
- rewriting engine with
+ them all in one directory. Before you put those instructions, don't
+ forget to turn on the rewriting engine with
<informalexample>
<programlisting role="apache-conf">
@@ -321,8 +338,7 @@
</programlisting>
</informalexample>
- My experiences have shown that you will need the following
- scripts:
+ You will need scripts:
<itemizedlist>
<listitem>
@@ -354,26 +370,57 @@
</listitem>
</itemizedlist>
</para>
+ <para>
+ As an alternative to the Rewrite Engine, you can also consider using
+ the Apache <literal>ErrorDocument</literal> directive, but be aware,
+ that <literal>ErrorDocument</literal> redirected pages cannot receive
+ POST data.
+ </para>
+ </section>
+
+ <section id="hyperwave.configuration">
+ &reftitle.runtime;
+ &no.config;
+ </section>
+
+ <section id="hyperwave.resources">
+ &reftitle.resources;
+ &no.resource;
</section>
- <section id="hw-todo">
+ &reference.hyperwave.constants;
+
+ <section id="hyperwave.todo">
<title>Todo</title>
<para>
- There are still some things todo:
+ There are still some things to do:
<itemizedlist>
- <listitem><simpara>The hw_InsertDocument has to be split into
+ <listitem>
+ <simpara>
+ The hw_InsertDocument has to be split into
<function>hw_insertobject</function> and
- <function>hw_putdocument</function>.</simpara></listitem>
- <listitem><simpara>The names of several functions are not fixed, yet.
- </simpara></listitem>
- <listitem><simpara>Most functions require the current connection
+ <function>hw_putdocument</function>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ The names of several functions are not fixed, yet.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Most functions require the current connection
as its first parameter. This leads to a lot of typing, which
is quite often not necessary if there is just one open
- connection. A default connection will
- improve this.</simpara></listitem>
- <listitem><simpara>Conversion form object record into object array
+ connection. A default connection will improve this.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Conversion form object record into object array
needs to handle any multiple attribute.
- </simpara></listitem>
+ </simpara>
+ </listitem>
</itemizedlist>
</para>
</section>
Index: phpdoc/en/reference/hwapi/reference.xml
diff -u phpdoc/en/reference/hwapi/reference.xml:1.4
phpdoc/en/reference/hwapi/reference.xml:1.5
--- phpdoc/en/reference/hwapi/reference.xml:1.4 Thu Apr 18 06:01:02 2002
+++ phpdoc/en/reference/hwapi/reference.xml Mon Jul 22 09:12:36 2002
@@ -1,23 +1,28 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.5 $ -->
<reference id="ref.hwapi">
<title>Hyperwave API functions</title>
<titleabbrev>Hyperwave API</titleabbrev>
<partintro>
- <section id="hwapi-intro">
- <title>Introduction</title>
+ <section id="hwapi.intro">
+ &reftitle.intro;
<para>
<productname>Hyperwave</productname> has been developed at
<ulink url="&url.iicm;">IICM</ulink> in Graz. It started with
the name <acronym>Hyper-G</acronym> and changed to Hyperwave when
- it was commercialised (If I remember properly it was in 1996).
+ it was commercialised (in 1996).
</para>
<para>
Hyperwave is not free software. The current version, 5.5, is
- available at <ulink url="&url.hyperwave;">www.hyperwave.com</ulink>.
+ available at <ulink url="&url.hyperwave;">&url.hyperwave;</ulink>.
A time limited version can be ordered for free (30 days).
</para>
<para>
+ See also the <link linkend="ref.hyperwave">Hyperwave</link> module.
+ </para>
+ <para>
Hyperwave is an information system similar to a database
(<acronym>HIS</acronym>, Hyperwave Information Server). Its focus
is the storage and management of documents. A document can be any
@@ -30,18 +35,49 @@
</para>
</section>
- <section id="hwapi-requirements">
- <title>Requirements</title>
+ <section id="hwapi.requirements">
+ &reftitle.required;
<para>
Since 2001 there is a Hyperwave SDK available. It supports Java,
JavaScript and C++. This PHP Extension is based on the C++ interface.
In order to activate the hwapi support in PHP you will have to install
- the Hyperwave SDK first and configure PHP with
+ the Hyperwave SDK first.
+ </para>
+ </section>
+
+ <section id="hwapi.installation">
+ &reftitle.install;
+ <para>
+ After installing the Hyperwave SDK, configure PHP with
<option role="configure">--with-hwapi=<dir$gt;</option>.
</para>
</section>
- <section id="hwapi-classes">
+ <section id="hwapi.apache">
+ <title>Integration with Apache</title>
+ <para>
+ The integration with Apache and possible other servers is already
+ described in the <link linkend="ref.hyperwave">Hyperwave module</link>
+ which has been the first extension to connect a Hyperwave Server.
+ </para>
+ </section>
+
+ <section id="hwapi.configuration">
+ &reftitle.runtime;
+ &no.config;
+ </section>
+
+ <section id="hwapi.resources">
+ &reftitle.resources;
+ &no.resource;
+ </section>
+
+ <section id="hwapi.constants">
+ &reftitle.constants;
+ &no.constants;
+ </section>
+
+ <section id="hwapi.classes">
<title>Classes</title>
<para>
The API provided by the HW_API extension is fully object oriented.
@@ -87,12 +123,12 @@
<para>
Each class has certain method, whose names are identical to its
counterparts in the Hyperwave SDK. Passing arguments to this function
- differs from all the other PHP Extension but is close to the C++ API of
+ differs from all the other PHP extensions but is close to the C++ API of
the HW SDK. Instead of passing serval parameters they are all put into
an associated array and passed as one paramter. The names of the keys
- are identical to those documented in the HW SDK.
- The common parameters are listed below. If other parameters are required
- they will be documented if needed.
+ are identical to those documented in the HW SDK. The common parameters
+ are listed below. If other parameters are required they will be
+ documented if needed.
<itemizedlist>
<listitem>
<simpara>
@@ -143,14 +179,6 @@
</simpara>
</listitem>
</itemizedlist>
- </para>
- </section>
- <section id="hwapi-apache">
- <title>Integration with Apache</title>
- <para>
- The integration with Apache and possible other servers is already
- described in the Hyperwave Modul which has been the first extension to
- connect a Hyperwave Server.
</para>
</section>
</partintro>
Index: phpdoc/en/reference/hw/constants.xml
+++ phpdoc/en/reference/hw/constants.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<section id="hyperwave.constants">
&reftitle.constants;
&extension.constants;
<variablelist>
<varlistentry>
<term>
<constant>HW_ATTR_LANG</constant>
(<link linkend="language.types.integer">integer</link>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>HW_ATTR_NR</constant>
(<link linkend="language.types.integer">integer</link>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>HW_ATTR_NONE</constant>
(<link linkend="language.types.integer">integer</link>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
<!-- 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
