nlopess Sun Sep 11 15:37:41 2005 EDT
Modified files:
/phpdoc/howto README generating.xml scripts.xml
Log:
remove the XSL chapter, as it was outdated. moved the interesting info to the
genearting chapter
document the iniupdate scripts
bring the README up-to-date
http://cvs.php.net/diff.php/phpdoc/howto/README?r1=1.5&r2=1.6&ty=u
Index: phpdoc/howto/README
diff -u phpdoc/howto/README:1.5 phpdoc/howto/README:1.6
--- phpdoc/howto/README:1.5 Thu Oct 24 20:36:27 2002
+++ phpdoc/howto/README Sun Sep 11 15:37:41 2005
@@ -7,33 +7,24 @@
document's HTML formatting (see phpdoc/howto.dsl), so it can't be
that different.
-Also, once you've loaded howto.xml into emacs, (you do use
-emacs+psgml don't you?) be sure to parse the DTD and then save
-it as howto.ced in the same directory as howto.xml.
+Also, if you use emacs+psgml be sure to parse the DTD and then
+save it as howto.ced in the same directory as howto.xml.
+
+To test the XML files for errors type:
+
+ make test_howto
To generate HTML format from the xml file, go to the phpdoc
directory, and type:
make howto
-
+
The HTML files will be generated in the html subdir of the
-howto directory. Also, if you don't feel like generating it
-yourself, this html version is also stored in the phpdoc
-howto directory. To uncompress, consider:
+howto directory.
- tar xfvz howto.html.tar.gz
-
A copy is also available online at:
http://www.php.net/dochowto
-If you'd like to see the latest build.log for the online
-PHP manual, it can be seen online. Replace {LANG} with
-your desired build log, such as en, fr or de:
-
- http://www.php.net/{LANG}/blog
-
If you have any questions, suggestions or flames, please
send them to the phpdoc mailing list: [EMAIL PROTECTED]
-
-Original author: Daniel Beckham <[EMAIL PROTECTED]>
http://cvs.php.net/diff.php/phpdoc/howto/generating.xml?r1=1.18&r2=1.19&ty=u
Index: phpdoc/howto/generating.xml
diff -u phpdoc/howto/generating.xml:1.18 phpdoc/howto/generating.xml:1.19
--- phpdoc/howto/generating.xml:1.18 Wed Mar 30 15:26:22 2005
+++ phpdoc/howto/generating.xml Sun Sep 11 15:37:41 2005
@@ -114,7 +114,8 @@
<command>xmllint</command> check on the entire phpdoc tree. This
will find problems <command>make test</command> ignores, problems like a
missing ; or & for an entity. <command>xmllint</command> is much
- slower than the SGML check and will take roughly 4 times longer to execute.
+ slower than the SGML check and will take roughly 4 times longer to execute
+ (and will consume much more memory).
</para>
<para>
<informalexample>
@@ -229,6 +230,15 @@
</para>
<para>
+ There are also XSL stylesheets available, that are equivalents to the above
+ DSSSL sheets. The list includes: <literal>html_xsl</literal>,
+ <literal>bightml_xsl</literal>, <literal>phpweb_xsl</literal>,
+ <literal>howto_xsl</literal>, <literal>chm_xsl</literal> and
+ <literal>fo</literal> (produces a FO file, that can be later transformed to
+ PDF using a FO processor, like Apache FOP)
+ </para>
+
+ <para>
To generate a viewable copy of the documentation,
<command>cd</command> to the <filename>phpdoc</filename> directory
and issue one of the following commands:
@@ -237,14 +247,14 @@
$ make html
$ make bightml
$ make phpweb
-$ make pdf
-$ make rtf
</programlisting>
</informalexample>
To make an actual copy of this HOWTO:
<informalexample>
<programlisting>
$ make howto
+ -or-
+$ make howto_xsl
</programlisting>
</informalexample>
The plain text version of the PHP documentation is made
@@ -255,7 +265,7 @@
<para>
Generating viewable documentation is CPU intensive and can take a
little while to complete. E.g. generating the simple HTML
- manual takes about 7m 30s on a 700MHz box.
+ manual takes about 1 hour on a normal computer.
</para>
</note>
@@ -273,116 +283,16 @@
documentation, including any changes you've made.
</para>
- </chapter>
-
- <chapter id="chapter-using-xsl">
- <title>Using XSL Stylesheets</title>
-
- <para>
- Currently using XSL stylesheets to generate output
- of XML files is not as well supported as using DSSSL
- style sheets. This is because XSL stylesheets are not
- as customized as DSSSL ones, and XSL tools are not as
- widely used, and standardized.
- </para>
-
- <para>
- At this time there are no XSL specific targets in
- <filename>Makefile</filename>. This is because there
- are not standardized ways to invoke XSLT processors.
- To use XSL stylesheets you must run the
- <filename>configure</filename> script and tell it,
- where your copy of XSL DocBook Stylesheets is placed.
- The majority of XSLT processors require an URL instead
- of a filename, so be sure to prepend
- the <literal>file:///</literal> schema before path:
- <informalexample>
- <programlisting>
-$ autoconf
-$ ./configure --with-xsl=file:///path/to/docbook/xsl/styles
- </programlisting>
- </informalexample>
- </para>
-
- <note>
- <para>
- The above <literal>--with-xsl=file:///path/to/docbook/xsl/styles</literal>
- form won't work with cygwin, because it tries to check for the existance
- of the style sheet, and cygwin cannot interpret this kind of file path.
- So there is a temporary
<literal>--with-mxsl=file:///path/to/docbook/xsl/styles</literal>
- method to use under cygwin, as long as we are unable to find the common
- right method. Please also note, that the file path values generated
- into <filename>entities/file-entities.ent</filename> by configure will
- also be problematic with current XSLT tools, so you need to convert them
- to use this <filename>file:///absolute/path/filename.xml</filename> form
- before running any XSLT processors... After going through all these your
- XSLT tool will be able to generate the output correctly under cygwin.
- </para>
- </note>
-
- <para>
- Configure will create four files:
- <filename>html.xsl</filename>,
- <filename>bightml.xsl</filename>,
- <filename>htmlhelp.xsl</filename>,
- <filename>print.xsl</filename> among others. These files
- can be used to generate the desired output.
- <filename>html.xsl</filename> generates a set of small
- HTML files, <filename>bightml.xsl</filename> generates
- one large HTML file, <filename>htmlhelp.xsl</filename>
- generates source files processable by HTML Help Workshop
- and <filename>print.xsl</filename> generates a file
- with FO objects suitable for further processing with
- some FO processor.
- </para>
-
- <note>
- <para>
- The <filename>htmlhelp.xsl</filename> is currently not too
- useful alone, as it's used by the new CHM build system which
- is not available in CVS right now.
- </para>
- </note>
-
- <para>
- Invocation of XSLT processor is processor dependent,
- for now suppose that you have a shell script called
- <filename>saxon</filename> which is able to invoke the
- Saxon processor. Some examples:
- <informalexample>
- <programlisting>
-$ mkdir html
-$ saxon manual.xml html.xsl
-$ saxon manual.xml htmlhelp.xsl
-$ saxon -o bigmanual.html manual.xml bightml.xsl
-$ saxon -o manual.fo manual.xml print.xsl
- </programlisting>
- </informalexample>
- Use the appropriate command from the examples above
- to generate the desired output as described above.
- To get a PDF from the FO file, you must run some FO
- processor on the <filename>manual.fo</filename> file.
- </para>
-
- <note>
+ <tip>
<para>
- Generating <filename>bigmanual.html</filename> with Saxon
- (using JDK 1.3) takes about two minutes on a Celeron 400
- computer. Generating FO files takes about two times more
- + plus time required to run the FO processor. Generating
- chunked version or HTML Help version of manual takes about
- 60 minutes.
+ Instead of generating the whole manual (which takes too much time), you
+ can generate just a single senction, by issuing the following command:
+ <command>xsltproc --stringparam rootid "<ID>" xsl/html.xsl
+ manual.xml</command> (replacing <literal><ID></literal> by the ID of
+ the file/section you want to build.
</para>
- </note>
-
- <note>
- <para>
- Not all customization from DSSSL are ported to XSL,
- so some things are not as pretty as in DSSSL output
- <emphasis>currently</emphasis>, but development is
- underway to migrate the system to use XSL only.
- </para>
- </note>
+ </tip>
+
</chapter>
<chapter id="chapter-online-generation">
http://cvs.php.net/diff.php/phpdoc/howto/scripts.xml?r1=1.3&r2=1.4&ty=u
Index: phpdoc/howto/scripts.xml
diff -u phpdoc/howto/scripts.xml:1.3 phpdoc/howto/scripts.xml:1.4
--- phpdoc/howto/scripts.xml:1.3 Thu Sep 8 10:09:02 2005
+++ phpdoc/howto/scripts.xml Sun Sep 11 15:37:41 2005
@@ -148,7 +148,7 @@
</para>
</note>
</sect1>
-
+
<sect1 id="scripts.html-syntax.php">
<title>html_syntax.php</title>
<para>
@@ -156,7 +156,38 @@
both for the online and downloadable manuals.
</para>
</sect1>
-
+
+ <sect1 id="scripts.iniupdate">
+ <title>iniupdate/*.php</title>
+ <para>
+ The <filename>iniupdate</filename> directory contains a set of scripts that
+ are used to generate the <filename>en/appendices/ini.xml</filename> table.
+ They also update the information that is dispersed in the
+ <filename>en/reference/*/ini.xml</filename> files.
+ </para>
+ <para>
+ To use this script, you must download all the PHP 4, 5 and 6 sources (which
+ will take a long time), so that the script can create a DB with the history
+ of the changes between the versions. To do that, you can just run the
+ <command>./update-all</command> script. If you are using the 'functable'
+ script as well, you may just create a symlink to its sources, as the
+ sources are the same :) The rest of the process is explained in the README
+ file.
+ </para>
+ <para>
+ The core of the scripts is in <filename>ini_search_lib.php</filename>, and
+ it is very regex based. The main regexes work correctly, although some
+ heuristics are used to catch the <function>cfg_get_*</function> uses. The
+ <filename>generate_changelog.php</filename> is used to generate the
+ changelog (based on the data previously collected in the DB).
+ </para>
+ <note>
+ <para>
+ This script requires PHP >= 5 with SQLite.
+ </para>
+ </note>
+ </sect1>
+
<sect1 id="scripts.xml-check.php">
<title>xml-check.php</title>
<para>
