[PHP-DOC] Livedocs, the future

Mehdi Achour Tue, 20 Jan 2004 07:22:10 -0800

Hi folks !

4 hours in the train, enough to dream.. I've tried to imagine the best evolution for livedocs, and I've seen one major modification needed : Separation

Actually, we have three main parts :
 - Build
 - XML parsing
 - HTML rendering

When livedocs was available through CVS, I've checked it out and started to adapt its design for my own website. While doing this, I fixed some bugs (BAD ID:..) and added some features like showing the available languages in the Index, and so on. When I wanted to commit my changes, I've seen that the noise caused by my design stuff was to huge. So I was unable to commit it.

This is why I would like to really divide the livedoc repository in the three mentionned parts. Lemme `tree` it :

[EMAIL PROTECTED]:~/livedocs$ tree -a
.
|-- BUGS
|-- README
|-- TODO
|-- build
|   |-- .htaccess.in
|   |-- build-ops
|   |-- build.sh
|   |-- config.php.in
|   |-- configure.in
|   |-- mkindex.php
|   |-- mktoc.php
|   |-- stop_list
|   `-- toc.xsl
|-- src
|   |-- error.php
|   |-- index.php
|   `-- xml_classes.php
`-- themes
    |-- default
    |   |-- README
    |   |-- error.php
    |   |-- formatting.php
    |   |-- index.php
    |   |-- livedocs.css
    |   `-- man.php
    `-- php.net
        |-- README
        |-- error.php
        |-- formatting.php
        |-- index.php
        |-- livedocs.css
        `-- man.php

DETAILS :

I - ~/livedocs/ :
  BUGS, README, TODO

same as the actual ones.

II - ~/livedocs/build/

all the build stuff go there.

III - ~/livedocs/src/

the xml processing stuff and some additionnal features (list of available languages, better search engine, etc etc)

IV - ~/livedocs/themes/

This is the "skins" directory. We'll keep the original skin under the name of "default" and it will be used in case of problems.

V - ~/livedocs/themes/php.net/

  - README : copyright for the theme
  - error.php : template for the error page
  - index.php : template for the (new and improved) index
  - man.php : template for a manual page
  - livedocs.css : the theme's css
  - formatting.php : all the XML => HTML transitions

As for the templating, I propose the following as each site will try to add it's own feature. ~/livedocs/themes/yourtheme/*.php will only contain rendering functions, called by src/*.php

In src/*.php we'll have such calls :

foo.php :
<?php
  include 'themes/' . $skin . '/foo.php';

  before_head();
  // some code
  head();

  after_head();
  // some more code
  print_page();

before_footer();

footer();

  after_footer();
?>

I'm imagining it while typing this mail, so this may be completely bogus / stupid.

BENEFITS :

- One can start it's own theme without having to co another copy of livedocs - By separating the differents parts, we make livedocs more easy to understand (I've stuggled, yay) - We'll be able to add a theme for PEAR and GTK docs - We'll have more contributions (as the problem I've faced at the start won't happen again)

This is only a first draft, I would like to have a lot of feedbacks/votes/opinions.

the ball is in your camp :)

Mehdi

[PHP-DOC] Livedocs, the future

Reply via email to