New capabilities via PhD

[weierophinney]

Greetings, all --

One important announcement for 1.10.0 is that we're now using PhD when
rendering documentation both for packaging as well as the online
documentation. PhD is php.net's documentation parser/renderer, and is
written entirely in PHP. It is lightning fast -- I can render a single
language in 20-30s on average (as opposed to ~10m using xsltproc).

One other reason for choosing PhD is to have more control over output.
As an example, I added support today for virtual thumbnails -- when
images are detected by the parser, it checks the dimensions, and, if the
width is > 450px, it will scale down the dimensions for the <img> tag
and then link the image.  (I've just now implemented this in the
LiveDocx chapter, where we were using that sort of functionality.)

If you are interested in using PhD to render ZF documentation, use the
following steps:

 * First, PhD requires PHP >= 5.3.0.

 * Check out:
   http://framework.zend.com/svn/framework/build-tools/trunk/build-tools/docs/

 * From your language's manual directory:
   * autoconf && ./configure
   * xsltproc --xinclude path/to/build-tools/docs/db4-upgrade.xsl manual.xml.in > manual-db5.xml
   * path/to/build-tools/docs/phd -g 'phpdotnet\phd\Highlighter_GeSHi' --xinclude -f zfpackage -d manual-db5.xml

The first step should be familiar. The second step converts our manual
to DocBook 5 standards. The third step builds the documentation.

Docs will now be in output/zf-package-chunked-xhtml/; the manual.html
file is the landing page.

Let me know if you have any questions, requests, etc.

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc

[mikaelkael]

Hi,

This is only valid for English manual because of our recent
modification: only one manual.xml.in in English directory.

For translation, you need to insert the copy of the manual and to rename
manual.xml.in:
   * autoconf && ./configure
   * make -e manual.xml
   * xsltproc --xinclude path/to/build-tools/docs/db4-upgrade.xsl
manual.xml > manual-db5.xml
   * path/to/build-tools/docs/pear/phd -g
'phpdotnet\phd\Highlighter_GeSHi' --xinclude -f zfpackage -d manual-db5.xml

Be careful with little translations, the xi:fallback mechanism eats a
lot of memory.

Mickael

Le 02/02/2010 22:31, Matthew Weier O'Phinney a écrit :

> Greetings, all --
>
> One important announcement for 1.10.0 is that we're now using PhD when
> rendering documentation both for packaging as well as the online
> documentation. PhD is php.net's documentation parser/renderer, and is
> written entirely in PHP. It is lightning fast -- I can render a single
> language in 20-30s on average (as opposed to ~10m using xsltproc).
>
> One other reason for choosing PhD is to have more control over output.
> As an example, I added support today for virtual thumbnails -- when
> images are detected by the parser, it checks the dimensions, and, if the
> width is>  450px, it will scale down the dimensions for the<img>  tag
> and then link the image.  (I've just now implemented this in the
> LiveDocx chapter, where we were using that sort of functionality.)
>
> If you are interested in using PhD to render ZF documentation, use the
> following steps:
>
>   * First, PhD requires PHP>= 5.3.0.
>
>   * Check out:
>     http://framework.zend.com/svn/framework/build-tools/trunk/build-tools/docs/
>
>   * From your language's manual directory:
>     * autoconf&&  ./configure
>     * xsltproc --xinclude path/to/build-tools/docs/db4-upgrade.xsl manual.xml.in>  manual-db5.xml
>     * path/to/build-tools/docs/phd -g 'phpdotnet\phd\Highlighter_GeSHi' --xinclude -f zfpackage -d manual-db5.xml
>
> The first step should be familiar. The second step converts our manual
> to DocBook 5 standards. The third step builds the documentation.
>
> Docs will now be in output/zf-package-chunked-xhtml/; the manual.html
> file is the landing page.
>
> Let me know if you have any questions, requests, etc.
>    

[chris.de2]

Hi,

i just used this instuctions and it worked.

But I got an parser error with the file Zend_Feed_Writer.xml:

chris@daimyo:~/work/src/zend/trunk/documentation/manual/de$ xsltproc --xinclude ../../../../build-tools/db4-upgrade.xsl manual.xml > manual-db5.xml
module_specs/Zend_Feed_Writer.xml:171: parser error : Opening and ending tag mismatch: programlisting line 151 and title
        <title type="html"><![CDATA[All Your Base Are Belong To Us]]></title>
                                                                             ^
module_specs/Zend_Feed_Writer.xml:190: parser error : Opening and ending tag mismatch: sect2 line 94 and entry
    </entry>
            ^
module_specs/Zend_Feed_Writer.xml:191: parser error : Opening and ending tag mismatch: sect1 line 4 and feed
</feed>
       ^
module_specs/Zend_Feed_Writer.xml:192: parser error : Extra content at the end of the document
]]></programlisting>
^
Converting ulink to uri. (manual)
Converting ulink to link. (manual)

This is a problem of the nested CDATA section.
If you render the english manual there is no error. I compared the english and the german file and found that the english version uses additional "]]><![CDATA[" (without the quotes) after each CDATA section which is inside another CDATA section.

As I still have no subversion write access I created a patch of Zend_Feed_Writer.xml and will submit it as ticket in Jira as soon as it is available again.

Greetings
Christoph