vendredi 27 juin 2008

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 ?


samedi 21 juin 2008

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 !

vendredi 13 juin 2008

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)

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

See you

samedi 7 juin 2008

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

lundi 2 juin 2008

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 theme. Here is an example of a PhD-rendered CHM file :

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 :
Docbook reference website :
GSoC Project webpage :