GSoC officially ends...

Hi !

The Google Summer of Code has finally ended the August 18th. The three outputs formats I planned to do are available (CHM, PDF, Manpage) and one of the two project specific "themes" (PEAR done, not PHP-GTK).

I also wrote a KDevelop format (which render an index and a TOC of the PHP Manual for the KDevelop application) and worked on PhD Enterprise, the last version (0.4.0).

I will keep working on PhD Enterprise until at least few working formats are moved to this new branch.

See you in another life :)
Rudy

Enterprise

Hi!

This week, I finished PDF output. When I began to move to the next scheduled item, DBHTML (Docbook processing instructions for HTML rendering) implementation, my mentor introduce a bigger project than ever: Enterprise PhD (v2.0-XP ^_^).

The main purpose is to clear the main defaults of PhD with a new implementation. XML Index informations are now stored on a SQLite3 database, Formats/themes "interface" has been renewed (now there are just formats which can be used as themes), Observer Design Pattern is used almost everywhere (with SplObjectStorage class of the Standard PHP Library), and formats have now access to more data.

I'm in charge of fixing bugs (my mentor wrote the main part of this new PhD), adding new features (it seems I have carte blanche), and (later) porting PhD formats I wrote.

See you next friday for raunchy news about ePhD :D
Rudy

Midterm assessment, PDF output done

Hi !

Time is come for a little summary of this project. What I had to do:
* To write new output formats: CHM, Manpages, PDF
* To write themes: PEAR HTML theme, PHP-GTK HTML theme
* To design DBHTML implementation in PhD

Currently, I'm done with CHM output, Manpage output format (and its own PHP theme) and PEAR theme for HTML format.

PDF is almost done (probably this weekend or next week). It remains two or three weeks to work on PHP-GTK theme and to begin PhD DBHTML implementation design.



As I said, PDF is almost over and renders good. My choice was to write two PHP themes: one which generates one PDF by PHP "book" and another which generates a big PDF (almost 10000 pages ^^) with all the PHP "books".

In prime exclusiveness ^_^ the big PDF version of PHP manual or zipped PDF chunks.

By the way, my mentor just release a new PhD release: PhD 0.3.0 (branch PHD_0_2, PHP 5.2 compliant).

See ya
Rudy

The hardest week

Hi !

Here was the hardest GSoC week ! I wrote a big part of the PDF output and both the themes "phppdf" (each PHP manual part in a file) and "phpbigpdf" (a big PDF file with all the sections).

Examples: Installation & Configuration chapter - Full Manual

What's done:
* PDF Table of content
* URL links
* internal links
* admonition paragraphs (tips, note, example, warning ...)
* bullet-lists
* tables (not finished)
* basic stuff (font/style/color changing, auto line wrap, line jumps, auto newline, ...)

If I'm good with tables, this output may be released the next week !

See you

haru/pecl wrapper

Hi !

I finished the PhD Manpage output this week ! Here are the PHP manpages. Unzip them in a folder and type 'man ./[function name].3' (for example 'man ./str_replace.3'), you'll see the corresponding man page.

The future PHP 5.3 release will be bundled with these man pages and a script which will allow you just type 'manphp str_replace'.

By the way, I've filled my Google Summer of Code midterm evaluation, I'm probably near behind schedule, that's why I began the new PhD output : PDF, the hardest one !

I use the Haru PDF library with pecl/haru to generate PDF. This library didn't support neither auto line break nor auto page break and is not very easy to use because it didn't allow to add text flows like PhD. That's why I began to wrote a wrapper which is very simple to use and which do auto line break and auto page break.

An example: here is a test of "PdfWriter", my wrapping class. You can watch the output here :

Currently, the words are cut but I'll fix that.

I plan to use the format (PDFPhDFormat) to build the PDF document with PdfWriter and the theme (phppdf or something) only to specify how to chunk the manual. It seems there will be one PDF by "book" (eg a PDF for Getting Started, another one for Installation and Configuration, etc.)

Next friday, maybe a first version of the PDF output...

See ya
Rudy

Few improvements to do

Hi

I am in progress with the Manpage output. All the required DB5 elements are processed. I have still to improve synopsises which could appear weirdly (especially in the case of the classes description when there are several synopsises items on a same manpage).

The last thing I'll do with Manpage is to generate reference summary function pages, to view all the documented functions ranked by category.

To compare with the last week screenshot:


A bad looking one (click to enlarge or view the untruncated pdf version and look at the several synopsises which appears in different places):


I think these improvements will be over in the middle of the next week :)

See ya
Rudy

Manpage output in progess...

Hi !

Here it is, the first month of coding is over !

I planned to do all the stuff excepts PDF output and DBHTML implementation before mid-July and I think it will be Ok.

Now, I'm implementing the PhD Manpage output format, which will allow Unix-users to view the PHP functions manual with the 'man' command.

I began this format at the begining of the week and and have already visible results.

For example, "man readfile" renders currently this manpage (click to enlarge):




(click here to compare with the online manual)

As you can see it's not finish yet, it needs improvements ! Maybe next week ?

Rudy

Almost one month !

Hi !

The first month of coding is almost over !

Assessment :
* CHM Output
* PEAR theme
And especially, I'm now confortable with PhD and know all what's necessary about it !

What's next? Maybe the Manpage output... I'll keep you informed !

See you !

PEAR theme done !

The PEAR theme is almost ready !

It remains some bugs that I'll try to fix before this week end:
* the table of contents on the top of the page can mismatch (especially in the "Packages" section)
* the questions in the section "Packages"->"PEAR"->"FAQ" aren't indexed successfully on the top of the page
* there is a small rendering issue with the "<pre>" tags (program listings, ...): there is always a newline in the end. The issue comes from the auto indent functionality of PhD.

The possibilities of rendering:
* one big-HTML file
* PHP files using the templates of the PEAR website and ready to put online
* chunked HTML files
* a CHM file (Windows Help with table of content, index & search functions)

To see the result
The code

Here is an example of manual page with CHM PEAR Theme:






See you
Rudy

Pear documentation

Here it is, the second week of coding is completed !

Unfortunately it was less efficient than last week... The next goal is to produce with PhD the Pear Documentation.

Unfortunately (again ^^), Pear Manual uses Docbook 4.3 and PhD can only process DB 5 files (and DB5 isn't backward compatible :/)... I began the week by trying to manually (with home made scripts) makes it a DB5 valid manual with reporting the major changes to do.

Then, I discover there is already an automatized way to do it ! It's a XSL transformation file located in the Docbook official website. Unfortunately (x3), it didn't work with the Peardoc which is chunked and includes many entities, because XSLT can't know the structure of a XML document which have entities inclusions...

Finally, I tried to migrate the manual from a assembled DB4.3 valid manual. It worked better, but there are still errors...

So, in this end of week, I begin to code the PhD Pear theme by using as a reference the fake DB5 Peardoc I made !

I hope I'll be better next week !

See you next friday

SoC begins

Last monday (May 26th), the Google Summer of Code program officially started !

The project I'm involved in is PhD. What's PhD? It's a PHP-based Docbook renderer which take a Docbook file in input and render it on various formats. Now, the only output format is XHTML but the purpose of my work is to render CHM, PDF and Unix-manpage formats and to write themes to render documentation for PHP related projects (Pear, PHP-GTK).

So, after a phase of documentation reading, I was ready to begin to code !

I began the project with the CHM renderer, which is now done for the PHP.net theme. Here is an example of a PhD-rendered CHM file : http://iutinfoa1.free.fr/SoC/php_manual_en.chm.

CHM is a Microsoft proprietary format, so it can be compiled only with a Microsoft tool : HTML Help Workshop (free to use, happily). The purpose was to generate Help Workshop project files : a description of the CHM file (.hhp), the table of content (.hhc) and the index (.hhk) which will be processed by Help Workshop.

Like all the proprietary tools, it has weaknesses and many undocumented troubles... The main issue I had is with the format of the table of content. All the element are in a HTML ul-li list and there is as much of lists as the number of subelements. All element is in an "object" markup. And guess what? If you wrap a line between the "li" markup and the "object" markup, Help Workshop will not compile !!! And because it's very well documented, the only help it give is "Please check the space available on your hard drive" ! Good to know, isn't it? :)

So, what's done this week? CHM rendering with stylesheet for PHP theme ! First step : helping Pear guys to migrate from Docbook 4.3 documentation to Docbook 5 and code a Pear theme.

See you friday !

PhD Wiki : http://doc.php.net/wiki/phd
Docbook reference website : http://www.docbook.org/
GSoC Project webpage : http://code.google.com/soc/2008/php/appinfo.html?csaid=3D5258783F22F62C