Tuesday, October 2, 2007

PhD: The [PH]P based [D]ocbook renderer RC1 released


Quick note; We released PhD0.1RC1 today \o/

Building the php.net documentations has never been as easy or as fast.

Note: You'll need 200M free diskspace (90M for the phpdoc XML sources and 110M for the generated html/php files).

  • Fetching the phpdoc sources:

    bjori@lindsay:~$ cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
    cvs checkout: Updating phpdoc
    U phpdoc/.cvsignore
    U phpdoc/LICENSE
    U phpdoc/Makefile.in
    [snip]

  • Configure and test the XML

    bjori@lindsay:~$ cd phpdoc/
    bjori@lindsay:~/phpdoc$ php configure.php
    configure.php: $Id: configure.php,v 1.7 2007/10/02 12:03:16 bjori Exp $
    PHP version: 5.3.0-dev
    [snip]
    * No missing ids found
    All good.
    All you have to do now is run 'phd /home/bjori/phpdoc'


  • Installing and rendering the php.net documentation

    bjori@lindsay:~/phpdoc$ cd ..
    bjori@lindsay:~$ pear install http://doc.php.net/phd/PhD-0.1RC1.tgz
    downloading PhD-0.1RC1.tgz ...
    Starting to download PhD-0.1RC1.tgz (19,683 bytes)
    .......done: 19,683 bytes
    install ok: channel://__uri/PhD-0.1RC1
    bjori@lindsay:~$ mkdir build
    bjori@lindsay:~$ cd build/
    bjori@lindsay:~/build$ time phd /home/bjori/phpdoc
    Creating php/toc/manual.inc...
    Creating php/toc/introduction.inc...
    Creating php/toc/getting-started.inc...
    [snip]
    Creating php/toc/userlandnaming.inc...
    Creating php/toc/about.inc...
    Creating php/toc/opl.license.inc...

    real 1m40.448s
    user 1m20.309s
    sys 0m6.420s
    bjori@lindsay:~/build$ ls -l
    total 26M
    -rw-r--r-- 1 bjori users 26M 10-02 12:28 bightml.html
    drwxr-xr-x 2 bjori users 364K 10-02 12:28 html/
    drwxr-xr-x 3 bjori users 336K 10-02 12:28 php/
    bjori@lindsay:~/build$ ls php | wc -l
    6288


Thats right. It takes less than 2 minutes (on my two years old Precision M70 laptop) to render the entire php.net documentations in three formats.


To celebrate the release we have registered a new "special" mirror, docs.php.net,
which is running these experimental builds of PhD, and would like to request
that people take a quick look at it before we start pushing these builds out
to the rest of the mirrors.

There is currently no known bug in these builds so if you find one then
please file a bug report or at least let us know about it.
I don't care how small or major the bug is, a missing whitespace or a
whole page missing, let us know if you find anything.


-Hannes


12 comments:

  1. It seems like a lot of the stuff (such as the comments) are bold, and it kind of makes it harder to read.

    ReplyDelete
  2. Schmalls: Where exactly?
    I'm not seeing any "extra" bold paragraphs in the manual nor the comments.

    ReplyDelete
  3. I don't see the bold problem now. I was on a computer at work that was running IE7, but I checked it with both Firefox 2.0.0.7 and IE 6.0 on my home computer. I will check it again when I go to work and see if it I can reproduce it.

    ReplyDelete
  4. Philip noticed the same problem.
    Its already fixed in CVS http://news.php.net/php.doc.cvs/127 :)

    ReplyDelete
  5. Yeah, there doesn't seem to be a problem now.

    ReplyDelete
  6. Empty table cells are rendered ugly in IE 7:
    http://tmp.markwiesemann.eu/tables.png

    That's likely caused because the td tag isn't closed for empty cells. (It might also need some dummy content to be rendered correctly, e.g.  .)

    ReplyDelete
  7. Mark: Fixed

    Thanks Mark & Schmalls! :)

    ReplyDelete
  8. Are there any plans to improve the display of the OO part of the API? Something more like JavaDoc would be useful, now the PHP API is becoming more and more OO

    ReplyDelete
  9. Jorrit: Yup. We are planning a major upgrade to the OO documentations.
    Initial draft can be found on livedocs.phpdoc.info (all comments greatly appreciated).

    ReplyDelete
  10. Is PhD useful only for the PHP docs, or would it accept arbitrary DocBook source and produce something somewhat presentable?

    ReplyDelete
  11. Larry: The goal of the project is to become an generic Docbook renderer, but at the moment it only has a "php.net theme".
    A "standard" theme will be part of PhD in the very near future.

    ReplyDelete
  12. This comment has been removed by a blog administrator.

    ReplyDelete