cvs: phpdoc /howto README generating.xml scripts.xml
| From: | Nuno Lopes | Date: | Sun, 11 Sep 2005 19:37:41 +0000 |
| Subject: | cvs: phpdoc /howto README generating.xml scripts.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969370093@lists.php.net to get a copy of this message | ||
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: phpdoc@lists.php.net. - -Original author: Daniel Beckham <danbeck@scott.net> 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>
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: phpdoc@lists.php.net. - -Original author: Daniel Beckham <danbeck@scott.net> 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>