Hi all,
My name is Moacir de Oliveira and I am the GSoC student working on PhD. In
this first week, I'm working in a new feature for PhD, the --package option.
Follows a brief explanation as well as the patches with the implementation.
Implementation of the --package option in PhD.
This proposal is based in the design pattern Abstract Factory, and only
compatible with PHD_ENTERPRISE yet.
The main idea is: when you have a new "package" of formats (to render some
book or documentation), all you have to do is paste the formats in a folder
and run PhD. Nowadays, we can't create a new set of classes for rendering
some book or documentation without modify the main code of PhD. With this
implementation the new packages will be "plug and play".
Example: If you have a new set of formats for rendering Docbook: The
Definitive Guide 5, you will have to paste the files in a folder with the
name of your package (TDG5) and paste in the packages directory.
Ex: packages/TDG5/
To make your package compatible with PhD you must write a concrete factory
that inherits PhDFormatFactory and implement the creational methods. The
name of your factory must follow the convention: <package_name>Factory. The
file must have the same name.
Ex: class TDG5Factory in the file TDG5Factory.class.php
And now run:
phd -d ../phpdoc/.manual.xml -f xhtml --package TDG5
If you skip the --package option a default package will be considered.
We don't need to modify the main code of PhD.
Package Example:
packages/TDG5/TDG5Factory.class.php
packages/TDG5/tdgxhtml.php
packages/TDG5/tdgbigxhtml.php
packages/TDG5/tdgphp.php
The classes in tdgxhtml.php, tdgphp.php etc. must inherit PhDFormat or
subclasses (example PhDXHTMLFormat).
After the implementation of this feature, the next step is make the current
formats generic enough for rendering other documentations.
I'm waiting for comments.
-Moacir
Index: config.php
===================================================================
RCS file: /repository/phd/config.php,v
retrieving revision 1.53.2.4
diff -u -r1.53.2.4 config.php
--- config.php 1 Aug 2008 18:57:52 -0000 1.53.2.4
+++ config.php 28 May 2009 02:07:43 -0000
@@ -37,6 +37,7 @@
'user_error_color' => false,
'phd_info_output' => NULL,
'phd_info_color' => false,
+ 'package' => 'PHP',
);
public static function init(array $a) {
<?php
abstract class PhDFormatFactory {
public function createXhtmlFormat() {}
public function createBigXhtmlFormat() {}
public function createPHPFormat() {}
public static final function createFactory() {
global $ROOT;
$package = PhDConfig::package();
$classname = "{$package}Factory";
require_once $ROOT . "/packages/$package/$classname.class.php";
$factory = new $classname();
if (!($factory instanceof PhDFormatFactory)) {
throw new Exception("All Factories must inherit PhDFormatFactory");
}
return $factory;
}
}
?>
Index: include/PhDBuildOptions.class.php
===================================================================
RCS file: /repository/phd/include/PhDBuildOptions.class.php,v
retrieving revision 1.6.2.4
diff -u -r1.6.2.4 PhDBuildOptions.class.php
--- include/PhDBuildOptions.class.php 1 Aug 2008 11:02:04 -0000 1.6.2.4
+++ include/PhDBuildOptions.class.php 28 May 2009 02:08:22 -0000
@@ -20,6 +20,7 @@
"color:" => "c:", // Use color output if possible
"version" => "V", // Print out version information
"help" => "h", // Print out help
+ "package:" => "P:", // The package of formats
);
}
@@ -99,6 +100,9 @@
public function option_p($k, $v)
{
+ if ($k == "P") {
+ return $this->option_package($k, $v);
+ }
$this->option_partial($k, $v);
}
public function option_partial($k, $v)
@@ -119,6 +123,25 @@
PhDConfig::set_render_ids($render_ids);
}
+ public function option_package($k, $v) {
+ static $packageList = NULL;
+
+ if (is_null($packageList)) {
+ $packageList = array();
+ foreach (glob($GLOBALS['ROOT'] . "/packages/*") as $item) {
+ if (is_dir($item) && !($item == "." || $item == "..")) {
+ $packageList[] = basename($item);
+ }
+ }
+ }
+
+ if (in_array($v, $packageList)) {
+ PhDConfig::set_package($v);
+ } else {
+ trigger_error("Invalid Package", E_USER_ERROR);
+ }
+ }
+
public function option_s($k, $v)
{
$this->option_skip($k, $v);
@@ -193,7 +216,7 @@
echo "Supported formats:\n";
echo "\t" . implode("\n\t", $formatList) . "\n";
- break;
+ //break;
exit(0);
}
<?php
require $ROOT . "/packages/PHP/xhtml.php";
require $ROOT . "/packages/PHP/bigxhtml.php";
require $ROOT . "/packages/PHP/php.php";
class PHPFactory extends PhDFormatFactory {
public function createXhtmlFormat() {
return new PhDXHTMLFormat();
}
public function createBigXhtmlFormat() {
return new PhDBigXHTMLFormat();
}
public function createPHPFormat() {
return new PhDPHPFormat();
}
}
?>
Index: render.php
===================================================================
RCS file: /repository/phd/Attic/render.php,v
retrieving revision 1.3.2.10
diff -u -r1.3.2.10 render.php
--- render.php 11 Aug 2008 12:46:48 -0000 1.3.2.10
+++ render.php 28 May 2009 02:07:22 -0000
@@ -11,9 +11,11 @@
require $ROOT . "/include/PhDFormat.class.php";
require $ROOT . "/include/PhDIndex.class.php";
-require $ROOT . "/formats/xhtml.php";
-require $ROOT . "/formats/bigxhtml.php";
-require $ROOT . "/formats/php.php";
+//require $ROOT . "/formats/xhtml.php";
+//require $ROOT . "/formats/bigxhtml.php";
+//require $ROOT . "/formats/php.php";
+
+require $ROOT . "/include/PhDFormatFactory.class.php";
//$INDEX = "/Users/loudi/Travail/phpdoc/.manual.xml";
//$FILENAME = "/Users/loudi/Travail/phpdoc/.manual.xml";
@@ -37,12 +39,13 @@
"verbose" =>
VERBOSE_ALL^(VERBOSE_PARTIAL_CHILD_READING|VERBOSE_CHUNK_WRITING),
"lang_dir" => $ROOT . DIRECTORY_SEPARATOR . "include" .
DIRECTORY_SEPARATOR . "langs" . DIRECTORY_SEPARATOR,
- "phpweb_version_filename" => PhDConfig::xml_root() . DIRECTORY_SEPARATOR .
'phpbook' . DIRECTORY_SEPARATOR . 'phpbook-xsl' . DIRECTORY_SEPARATOR .
'version.xml',
+ "phpweb_version_filename" => PhDConfig::xml_root() . DIRECTORY_SEPARATOR .
'version.xml',
"phpweb_acronym_filename" => PhDConfig::xml_root() . DIRECTORY_SEPARATOR .
'entities' . DIRECTORY_SEPARATOR . 'acronyms.xml',
));
$render = new PhDRender();
$reader = new PhDReader();
+$factory = PhDFormatFactory::createFactory();
// Indexing & registering formats
foreach(range(0, 0) as $i) {
@@ -66,13 +69,13 @@
foreach (PhDConfig::output_format() as $format) {
switch($format) {
case "xhtml": // Standalone Chunked xHTML Format
- $render->attach(new PhDXHTMLFormat());
+ $render->attach($factory->createXhtmlFormat());
break;
case "php": // Standalone phpweb Format
- $render->attach(new PhDPHPFormat());
+ $render->attach($factory->createPHPFormat());
break;
case "bigxhtml": // Standalone Big xHTML Format
- $render->attach(new PhDBigXHTMLFormat());
+ $render->attach($factory->createBigXhtmlFormat());
break;
}
}
