goba Tue Feb 26 16:08:08 2002 EDT
Modified files:
/phpdoc/howto howto.ent howto.html.tar.gz howto.xml tools.xml
working.xml
Log:
XSLT part:
Adding LibXSLT links
Removing XT links
Adding note on XT and MSXML cannot be used to build HTML
Files:
Updated file paths
Added DSSSL and XSL sheet [very] short path notes
Revcheck part:
Build log is now build.log.gz
Adding gz note for IE users
Adding translation.xml descriptions with optional
parameters described
Adding Credits comment info
Mailing lists:
Adding the CHM mailing list
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.12 phpdoc/howto/howto.ent:1.13
--- phpdoc/howto/howto.ent:1.12 Wed Jan 9 15:29:22 2002
+++ phpdoc/howto/howto.ent Tue Feb 26 16:08:06 2002
@@ -57,24 +57,25 @@
<!ENTITY url.cvs.faq "http://www.loria.fr/~molli/cvs/cvs-FAQ/cvsfaq0.html";>
<!-- XSL tools and utils links -->
-<!ENTITY url.xsl.xt "http://www.jclark.com/xml/xt.html";>
-<!ENTITY url.xsl.saxon "http://saxon.sourceforge.net/";>
-<!ENTITY url.xsl.xalan "http://xml.apache.org/xalan-j/";>
-<!ENTITY url.xsl.style "http://www.nwalsh.com/docbook/xsl/index.html";>
-<!ENTITY url.xsl.passivetex "http://users.ox.ac.uk/~rathz/passivetex/";>
-<!ENTITY url.xsl.fop "http://xml.apache.org/fop/";>
-<!ENTITY url.xsl.xep "http://www.renderx.com/";>
-<!ENTITY url.sunjava "http://java.sun.com/";>
+<!ENTITY url.xsl.libxslt "http://xmlsoft.org/";>
+<!ENTITY url.xsl.libxslt.win
+"http://www.fh-frankfurt.de/~igor/projects/libxml/index.html";>
+<!ENTITY url.xsl.saxon "http://saxon.sourceforge.net/";>
+<!ENTITY url.xsl.xalan "http://xml.apache.org/xalan-j/";>
+<!ENTITY url.xsl.style "http://www.nwalsh.com/docbook/xsl/index.html";>
+<!ENTITY url.xsl.passivetex "http://users.ox.ac.uk/~rathz/passivetex/";>
+<!ENTITY url.xsl.fop "http://xml.apache.org/fop/";>
+<!ENTITY url.xsl.xep "http://www.renderx.com/";>
+<!ENTITY url.sunjava "http://java.sun.com/";>
<!-- For Working section -->
<!ENTITY url.langcodes "http://www.unicode.org/unicode/onlinedat/languages.html";>
-<!ENTITY url.buildlog.de "http://www.php.net/manual/de/build.log";>
+<!ENTITY url.buildlog.de "http://www.php.net/manual/de/build.log.gz";>
<!ENTITY url.listarchive "http://marc.theaimsgroup.com/?l=phpdoc";>
<!ENTITY url.listnews "news://news.php.net/php.doc";>
<!ENTITY url.listnewshttp "http://news.php.net/group.php?group=php.doc";>
<!ENTITY url.docsubscribe "[EMAIL PROTECTED]">
<!ENTITY url.docunsubscribe "[EMAIL PROTECTED]">
-<!ENTITY url.support "http://www.php.net/support.php";>
+<!ENTITY url.maillists "http://www.php.net/mailing-lists.php";>
<!ENTITY url.status "http://toye.php.net/~rasmus/status.php";>
<!ENTITY url.status.hu "http://toye.php.net/~rasmus/status.php?l=hu";>
<!ENTITY url.revcheck.it "http://www.php.net/manual/it/revcheck.html";>
Index: phpdoc/howto/howto.html.tar.gz
Index: phpdoc/howto/howto.xml
diff -u phpdoc/howto/howto.xml:1.26 phpdoc/howto/howto.xml:1.27
--- phpdoc/howto/howto.xml:1.26 Thu Feb 7 15:15:29 2002
+++ phpdoc/howto/howto.xml Tue Feb 26 16:08:07 2002
@@ -18,19 +18,13 @@
<!-- TODO
- Document new behaviour, new phpdoc structure
- Add Gnome LibXSLT links:
- http://xmlsoft.org/ and for Windows:
- http://www.fh-frankfurt.de/~igor/projects/libxml/index.html
-
- Remove XT, as it cannot handle DocBook style sheets
+ Document new behaviour
Sections need to be added:
Documentation of the new CHM format generation
How to add a new section/funcref/anything to the docs
Work on Emacs and vi sections
Partical advice for manual writers
- Using translation.xml and CREDITS comments
Separate conventions to parts, eg.
- larger sections (eg. function explanations)
- type, function and other tags,
Index: phpdoc/howto/tools.xml
diff -u phpdoc/howto/tools.xml:1.5 phpdoc/howto/tools.xml:1.6
--- phpdoc/howto/tools.xml:1.5 Wed Dec 12 15:50:42 2001
+++ phpdoc/howto/tools.xml Tue Feb 26 16:08:08 2002
@@ -426,7 +426,10 @@
is not as well supported as DSSSL stylesheets,
but is a promising technology. You do not need
to setup any tools mentioned here if you would
- not like to play with XSL stylesheets.
+ not like to play with XSL stylesheets. However
+ we plan to use XSLT in the future for HTML
+ generation, and possibly PDF generation, if we
+ can manage to work out how to do it correctly.
</para>
</note>
@@ -435,21 +438,31 @@
<itemizedlist>
<listitem>
<simpara>
- XT: <ulink url="&url.xsl.xt;">&url.xsl.xt;</ulink>
+ Saxon: <ulink url="&url.xsl.saxon;">&url.xsl.saxon;</ulink>
</simpara>
</listitem>
<listitem>
<simpara>
- Saxon: <ulink url="&url.xsl.saxon;">&url.xsl.saxon;</ulink>
+ Xalan: <ulink url="&url.xsl.xalan;">&url.xsl.xalan;</ulink>
</simpara>
</listitem>
<listitem>
<simpara>
- Xalan: <ulink url="&url.xsl.xalan;">&url.xsl.xalan;</ulink>
+ Gnome LibXSLT: <ulink url="&url.xsl.libxslt;">&url.xsl.libxslt;</ulink>,
+ also available as Windows binary:
+ <ulink url="&url.xsl.libxslt.win;">&url.xsl.libxslt.win;</ulink>,
</simpara>
</listitem>
</itemizedlist>
</para>
+
+ <note>
+ <para>
+ As we tested, other XSLT processors, like XT and MSXML cannot handle
+ the DocBook XSL stylesheets, so these cannot be used for even
+ the simplest HTML creation.
+ </para>
+ </note>
<para>
XSL DocBook Stylesheets: <ulink url="&url.xsl.style;">&url.xsl.style;</ulink>
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.14 phpdoc/howto/working.xml:1.15
--- phpdoc/howto/working.xml:1.14 Sat Feb 2 09:14:22 2002
+++ phpdoc/howto/working.xml Tue Feb 26 16:08:08 2002
@@ -20,7 +20,7 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>chapters.ent</filename></term>
+ <term><filename>entities/chapters.ent</filename></term>
<listitem>
<simpara>
Contains entity definitions for all chapters and
@@ -30,7 +30,7 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><filename>global.ent</filename></term>
+ <term><filename>entites/global.ent</filename></term>
<listitem>
<simpara>
Global internal text entities for all the XML
@@ -40,6 +40,24 @@
</listitem>
</varlistentry>
<varlistentry>
+ <term><filename>dsssl/*</filename></term>
+ <listitem>
+ <simpara>
+ DSSSL style sheets we use to generate the available
+ formats of the manual.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>xsl/*</filename></term>
+ <listitem>
+ <simpara>
+ XSL style sheets to generate HTML, HTMLHelp and print
+ output from the manual XML sources.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><filename>your_language/language-defs.ent</filename></term>
<listitem>
<simpara>
@@ -669,7 +687,7 @@
sites, you can check out the building log
of the several downloadable formats and
online manuals by downloading the
- <filename>build.log</filename> file of your
+ <filename>build.log.gz</filename> file of your
language. For the German translation, this file is:
<ulink url="&url.buildlog.de;">&url.buildlog.de;</ulink>.
Substitute "de" with your own language code to
@@ -679,6 +697,15 @@
not updated online, it is a good idea, to look
into this file and see what was the error.
</simpara>
+ <simpara>
+ Note, that some browsers like MSIE may
+ uncompress the gz file on the fly and show
+ the log file in the browser window as text.
+ This also means, that if you download this gz
+ file with MSIE, the downloaded file name will
+ still hold the gz extension, while it will be
+ a simple text log file.
+ </simpara>
</listitem>
</itemizedlist>
</para>
@@ -802,21 +829,21 @@
</para>
<para>
Currently all the three information is needed. Maintainer
- is intended to be a CVS user name, status can be anything
- without a space. Note, that this header is not updated
- by CVS (as <literal>$Revision</literal> is updated
- automatically). This is only updated when you edit the
- contents of the comment.
+ is intended to be a CVS user name, or some nickname without
+ a space, status can be anything without a space. Note, that
+ this header is not updated by CVS (as
+ <literal>$Revision</literal> is updated automatically). This
+ is only updated when you edit the contents of the comment.
</para>
<para>
You may see this as a good thing, but using these comments,
you loose the quick look on the whole list of your
- files. No, you do not loose this, and get much more! If
+ files. No, you do not loose this, but get much more! If
you would like to build a list similar to the
<filename>Translators</filename> file given above, you
- can go to the scripts subdirectory of phpdoc, and run:
+ can go to the scripts directory and run:
<programlisting>
-./revcheck.php xx
+./revcheck.php xx > revcheck.html
</programlisting>
Here <literal>xx</literal> is the imaginary language code.
After running this script you'll get a
@@ -825,20 +852,99 @@
for all the files in this language. You can also
add a furter restriction parameter, the maintainer name,
so the script will only list the files corresponding to
- the given maintaner. This HTML files gives you much more
+ the given maintaner. This HTML file gives you much more
than the <filename>Translators</filename> file. See it
yourself for example with the Italian translation (code:
- it).
+ it). You can also easily run this with <literal>make
+ revcheck</literal> in the phpdoc root directory, in
+ case you issued a
+ <literal>./configure --with-lang=xx</literal> before.
</para>
+
<para>
As this system gets popular in many translation groups,
the automatic build process also generates a
- <filename>revcheck.html</filename> available online
+ <filename>revcheck.html</filename> at the end of the
+ build process for that language. It is available online
in the languages manual directory, as
- <filename>build.log</filename> is also there.
+ <filename>build.log.gz</filename> is also there.
See the Italian translation's file online:
<ulink url="&url.revcheck.it;">&url.revcheck.it;</ulink>.
</para>
+
+ <para>
+ There are some extensions introduced for this script,
+ as need arised to port all contents of the
+ <filename>Translators</filename> files to be available
+ in this generated HTML page. This is why the
+ <filename>translation.xml</filename> files are
+ introduced. Here comes a simple
+ <filename>translation.xml</filename> file
+ for the imaginary xx language (contents ported from
+ the <filename>Translators</filename> example above):
+ <programlisting>
+<![CDATA[
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE translation SYSTEM "../dtds/translation.dtd">
+
+<translation>
+
+ <intro>
+ This is some introductory text for the xx language translators
+ about who is the manager of the translation, and where to find
+ more information. This paragraph is printed on the top of the
+ generated revcheck.html page.
+ </intro>
+
+ <translators>
+ <person name="Joe Doe" email="[EMAIL PROTECTED]" nick="joedoe" cvs="yes"/>
+ <person name="Jane Smith" email="[EMAIL PROTECTED]" nick="jane" cvs="yes"/>
+ <person name="Joe Forever" email="[EMAIL PROTECTED]" nick="joefo" cvs="no"/>
+ </translators>
+
+ <work-in-progress>
+ <file name="appendices/aliases.xml" person="joedoe" type="working"/>
+ <file name="functions/dbx.xml" person="joefo" type="working"/>
+ </work-in-progress>
+
+</translation>
+]]>
+ </programlisting>
+ As you can see, this file can store exactly the same content,
+ as a <filename>Translators</filename> file. What is new in this
+ file, is that you can add users without a CVS account, and can
+ assign ready documents or work-in-progress files to them. The
+ biggest advantage of using this addon is that all this information
+ is used to generate dynamic tables of translators and files in
+ the <filename>revcheck.html</filename> file. All translators
+ are linked to from the individual files they are assigned
+ to, and there is a nice table showing the state of files for
+ all the translators.
+ </para>
+
+ <para>
+ There are two optional parameters you can add to a <file>,
+ if you would like to record it: the <literal>date</literal>
+ and <literal>revision</literal>. Date is assumed to be the date
+ when the work was started, revision is the checked out revision
+ of the English file used to start the work (denoted as
+ CO-Revision in the generated table).
+ </para>
+
+ <para>
+ Another addon to this system is just to give credit to all people
+ worked on one file, and not just the current maintainer. To achive
+ this goal, we added the credit comments. One credit comment in
+ eg. <filename>history.xml</filename> may look like this (in case
+ Joe Doe translated the file initally, but Jane followed him to
+ be the maintainer):
+ <programlisting>
+<!-- CREDITS: joedoe -->
+ </programlisting>
+ The credits comment can contain a comma separated list. These
+ comments only affect the display of the translators table in
+ <filename>revcheck.html</filename>.
+ </para>
</sect2>
<sect2 id="translation-revcheck-status">
@@ -874,7 +980,7 @@
</chapter>
<chapter id="chapter-maillist">
- <title>The phpdoc and php-notes Mailing Lists</title>
+ <title>The phpdoc, php-doc-chm and php-notes Mailing Lists</title>
<para>
The XML content of <literal>phpdoc</literal> files is
@@ -888,7 +994,7 @@
Similarly you can unsubscribe by sending a blank mail to
<ulink url="&url.docunsubscribe;">&url.docunsubscribe;</ulink>.
There is a web interface for these tasks at <ulink
- url="&url.support;">&url.support;</ulink>.
+ url="&url.maillists;">&url.maillists;</ulink>.
</para>
<para>
Currently this list receives messages from the following senders:
@@ -968,6 +1074,14 @@
into attachements. You can always see the commit message
and file list in the body, but the diff is in an
attachement.
+ </para>
+ <para>
+ As the Windows HTMLHelp Edition of the manual is evolving
+ in an incredible way, there is a separate mailing list for
+ CHM related discussions and announcements. You can subscribe
+ to this mailing list at <ulink
+ url="&url.maillists;">&url.maillists;</ulink> using the
+ web interface.
</para>
<para>
There is also a mailing list named <literal>php-notes</literal>.
