/**
* Create the extension documentation DocBook XML files
*
* @access public
* @param string Directory to write to
*/
function generateDocumentation($docdir)
{
$idName = str_replace('_', '-', $this->name);
$fp = new CodeGen_Tools_FileReplacer("{$docdir}/reference.xml");
$fp->puts("<?xml version='1.0' encoding='iso-8859-1'?>\n<!-- " . '$' . "Revision: 1.1 \$ -->\n <reference id='ref.{$idName}'>\n <title>{$this->summary}</title>\n <titleabbrev>{$idName}</titleabbrev>\n\n <partintro>\n <section id='{$idName}.intro'>\n &reftitle.intro;\n <para>\n{$this->description}\n </para>\n </section>\n \n &reference.{$idName}.configure;\n\n <section id='{$idName}.resources'>\n &reftitle.resources;\n");
if (empty($this->resources)) {
$fp->puts(" &no.resource;\n");
} else {
foreach ($this->resources as $resource) {
$fp->puts($resource->docEntry($idName));
}
}
$fp->puts(" </section>\n\n <section id='{$idName}.constants'>\n &reftitle.constants;\n");
if (empty($this->constants)) {
$fp->puts(" &no.constants;\n");
} else {
$fp->puts(CodeGen_PECL_Element_Constant::docHeader($idName));
foreach ($this->constants as $constant) {
$fp->puts($constant->docEntry($idName));
}
$fp->puts(CodeGen_PECL_Element_Constant::docFooter());
}
$fp->puts(" </section>\n \n </partintro>\n\n&reference.{$idName}.functions;\n\n </reference>\n");
$fp->puts($this->docEditorSettings());
$fp->close();
// configure options and dependencies have their own file
$fp = new CodeGen_Tools_FileReplacer("{$docdir}/configure.xml");
$fp->puts("\n <section id='{$idName}.requirements'>\n &reftitle.required;\n");
if (empty($this->libs) && empty($this->headers)) {
$fp->puts(" &no.requirement;\n");
} else {
// TODO allow custom text
if (isset($this->libs)) {
$libs = array();
foreach ($this->libs as $lib) {
$libs[] = $lib->getName();
}
$ies = count($libs) > 1 ? "ies" : "y";
$fp->puts("<para>This extension requires the following librar{$ies}: " . join(",", $libs) . "</para>\n");
}
if (isset($this->headers)) {
$headers = array();
foreach ($this->headers as $header) {
$headers[] = $header->getName();
}
$s = count($headers) > 1 ? "s" : "";
$fp->puts("<para>This extension requires the following header{$s}: " . join(",", $headers) . "</para>\n");
}
}
$fp->puts("\n </section>\n\n");
$fp->puts("\n <section id='{$idName}.install'>\n &reftitle.install;\n");
if (empty($this->with)) {
$fp->puts(" &no.install;\n");
} else {
foreach ($this->with as $with) {
if (isset($with->summary)) {
if (strstr($with->summary, "<para>")) {
$fp->puts($with->summary);
} else {
$fp->puts(" <para>\n" . rtrim($with->summary) . "\n </para>\n");
}
} else {
// TODO default text
}
}
}
$fp->puts("\n </section>\n\n");
$fp->puts("\n <section id='{$idName}.configuration'>\n &reftitle.runtime;\n");
if (empty($this->phpini)) {
$fp->puts(" &no.config;\n");
} else {
$fp->puts(CodeGen_PECL_Element_Ini::docHeader($this->name));
foreach ($this->phpini as $phpini) {
$fp->puts($phpini->docEntry($idName));
}
$fp->puts(CodeGen_PECL_Element_Ini::docFooter());
}
$fp->puts("\n </section>\n\n");
$fp->puts($this->docEditorSettings());
$fp->close();
@mkdir("{$docdir}/functions");
foreach ($this->functions as $name => $function) {
$filename = $docdir . "/functions/" . strtolower(str_replace("_", "-", $name)) . ".xml";
$funcfile = new CodeGen_Tools_FileReplacer($filename);
$funcfile->puts($function->docEntry($idName));
$funcfile->puts($this->docEditorSettings(4));
$funcfile->close();
}
}
/**
* Create the extension documentation DocBook XML files
*
* @access public
* @param string Directory to write to
*/
function generateDocumentation($docdir)
{
$idName = str_replace('_', '-', $this->name);
if (!@System::mkdir("-p {$docdir}/{$idName}")) {
return PEAR::raiseError("can't create '{$docdir}/{$idName}'", E_USER_ERROR);
}
$manual = new CodeGen_Tools_FileReplacer("{$docdir}/manual.xml.in");
$manual->puts("<?xml version='1.0' encoding='UTF-8' ?>\n<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'\n '@PHPDOC@/dtds/dbxml-4.1.2/docbookx.dtd' [\n\n<!-- Add translated specific definitions and snippets -->\n<!ENTITY % language-defs SYSTEM '@PHPDOC@/en/language-defs.ent'>\n<!ENTITY % language-snippets SYSTEM '@PHPDOC@/en/language-snippets.ent'>\n\n%language-defs;\n%language-snippets;\n\n<!-- Fallback to English definitions and snippets (in case of missing translation) -->\n<!ENTITY % language-defs.default SYSTEM '@PHPDOC@/en/language-defs.ent'>\n<!ENTITY % language-snippets.default SYSTEM '@PHPDOC@/en/language-snippets.ent'>\n<!ENTITY % extensions.default SYSTEM '@PHPDOC@/en/extensions.ent'>\n\n%language-defs.default;\n%language-snippets.default;\n%extensions.default;\n\n<!-- All global entities for the XML files -->\n<!ENTITY % global.entities SYSTEM '@PHPDOC@/entities/global.ent'>\n\n<!ENTITY % file.entities SYSTEM './file-entities.ent'>\n\n<!-- Include all external DTD parts defined previously -->\n%global.entities;\n%file.entities;\n\n<!-- Autogenerated missing entites and IDs to make build work -->\n<!ENTITY % missing-entities SYSTEM '@PHPDOC@/entities/missing-entities.ent'>\n%missing-entities;\n]>\n\n<book id='manual' lang='en'>\n &reference.{$idName}.reference;\n</book>\n");
$manual->close();
$makefile = new CodeGen_Tools_FileReplacer("{$docdir}/Makefile");
$makefile->puts("#\nall: html\n\nconfcheck:\n\t@if test \"x\$(PHPDOC)\" = \"x\"; then echo PHPDOC not set; exit 3; fi\n\nmanual.xml: manual.xml.in\n\tsed -e's:@PHPDOC@:\$(PHPDOC):g' < manual.xml.in > manual.xml\n\nhtml: confcheck manual.xml\n\trm -rf html; mkdir html\n\tSP_ENCODING=XML SP_CHARSET_FIXED=YES openjade -D \$(PHPDOC) -wno-idref -c \$(PHPDOC)/docbook/docbook-dsssl/catalog -c \$(PHPDOC)/phpbook/phpbook-dsssl/defaults/catalog -d \$(PHPDOC)/phpbook/phpbook-dsssl/html.dsl -V use-output-dir -t sgml \$(PHPDOC)/phpbook/phpbook-xml/phpdocxml.dcl manual.xml\n\nbightml: confcheck manual.xml\n\trm -rf html; mkdir html\n\tSP_ENCODING=XML SP_CHARSET_FIXED=YES openjade -D \$(PHPDOC) -wno-idref -c \$(PHPDOC)/docbook/docbook-dsssl/catalog -c \$(PHPDOC)/phpbook/phpbook-dsssl/defaults/catalog -d \$(PHPDOC)/phpbook/phpbook-dsssl/html.dsl -V nochunks -t sgml \$(PHPDOC)/phpbook/phpbook-xml/phpdocxml.dcl manual.xml > manual.html\n\ntex: manual.tex\n\nmanual.tex: confcheck manual.xml\n\tSP_ENCODING=XML SP_CHARSET_FIXED=YES openjade -D \$(PHPDOC) -wno-idref -c \$(PHPDOC)/docbook/docbook-dsssl/catalog -c \$(PHPDOC)/phpbook/phpbook-dsssl/defaults/catalog -d \$(PHPDOC)/phpbook/phpbook-dsssl/print.dsl -t tex \$(PHPDOC)/phpbook/phpbook-xml/phpdocxml.dcl manual.xml\n\npdf: manual.tex\n\tpdfjadetex manual.tex && pdfjadetex manual.tex && pdfjadetex manual.tex\n");
$makefile->close();
$entities = new CodeGen_Tools_FileReplacer("{$docdir}/file-entities.ent");
$entities->puts("<!ENTITY reference.{$idName}.reference SYSTEM './{$idName}/reference.xml'>\n");
$fp = new CodeGen_Tools_FileReplacer("{$docdir}/{$idName}/reference.xml");
$fp->puts("<?xml version='1.0' encoding='iso-8859-1'?>\n<!-- " . '$' . "Revision: 1.1 \$ -->\n");
// phpdoc comments according to http://doc.php.net/php/de/dochowto/x1257.php
$fp->puts("<!-- Purpose: " . $this->docPurpose . " -->\n");
$fp->puts("<!-- Membership: pecl");
if (count($this->with)) {
$fp->puts(", external");
}
$fp->puts(" -->\n");
if ($this->release->getState() !== 'stable') {
$fp->puts("<!-- State: experimental -->\n");
}
$fp->puts("\n <reference xml:id='ref.{$idName}' xmlns='http://docbook.org/ns/docbook' xmlns:xlink='http://www.w3.org/1999/xlink'>\n <title>{$this->summary}</title>\n <titleabbrev>{$idName}</titleabbrev>\n\n <partintro>\n <section id='{$idName}.intro'>\n &reftitle.intro;\n <para>\n{$this->description}\n </para>\n </section>\n\n <section xml:id='{$idName}.requirements'>\n &reftitle.required;\n <para>\n\n </para>\n </section>\n\n &reference.{$idName}.configure;\n &reference.extname.ini;\n\n <section id='{$idName}.resources'>\n &reftitle.resources;\n");
if (empty($this->resources)) {
$fp->puts(" &no.resource;\n");
} else {
foreach ($this->resources as $resource) {
$fp->puts($resource->docEntry($idName));
}
}
$fp->puts(" </section>\n\n &reference.extname.constants;\n </partintro>\n\n&reference.{$idName}.functions;\n\n </reference>\n");
$fp->puts($this->docEditorSettings());
$fp->close();
//
// constants.xml
//
$entities->puts("<!ENTITY reference.{$idName}.constants SYSTEM './{$idName}/constants.xml'>\n");
$fp = new CodeGen_Tools_FileReplacer("{$docdir}/{$idName}/constants.xml");
$fp->puts("<?xml version='1.0' encoding='iso-8859-1'?>\n<!-- " . '$' . "Revision: 1.1 \$ -->\n");
$fp->puts("<section id='{$idName}.constants' xmlns='http://docbook.org/ns/docbook' xmlns:xlink='http://www.w3.org/1999/xlink'>\n");
$fp->puts(" &reftitle.constants;\n");
$fp->puts(" &extension.constants;\n");
$fp->puts(" <para>\n");
if (empty($this->constants)) {
$fp->puts(" &no.constants;\n");
} else {
$const_groups = array();
foreach ($this->constants as $constant) {
$const_groups[$constant->getGroup()][] = $constant;
}
foreach ($const_groups as $group => $constants) {
if ($group == "default") {
$group = $idName;
}
$fp->puts(CodeGen_PECL_Element_Constant::docHeader($group));
foreach ($constants as $constant) {
$fp->puts($constant->docEntry($group));
}
$fp->puts(CodeGen_PECL_Element_Constant::docFooter());
}
}
// TODO: 2nd half missing, see http://doc.php.net/php/de/dochowto/c578.php
$fp->puts(" </para>\n");
$fp->puts("</section>\n");
$fp->puts($this->docEditorSettings());
$fp->close();
//
// ini.xml
//
$entities->puts("<!ENTITY reference.{$idName}.ini SYSTEM './{$idName}/ini.xml'>\n");
$fp = new CodeGen_Tools_FileReplacer("{$docdir}/{$idName}/ini.xml");
$fp->puts("<?xml version='1.0' encoding='iso-8859-1'?>\n<!-- " . '$' . "Revision: 1.1 \$ -->\n");
$fp->puts("<section id='{$idName}.configuration' xmlns='http://docbook.org/ns/docbook' xmlns:xlink='http://www.w3.org/1999/xlink'>\n");
$fp->puts(" &reftitle.runtime;\n");
$fp->puts(" &extension.runtime;\n");
$fp->puts(" <para>\n");
if (empty($this->phpini)) {
$fp->puts(" &no.config;\n");
} else {
$fp->puts(CodeGen_PECL_Element_Ini::docHeader($this->name));
foreach ($this->phpini as $phpini) {
$fp->puts($phpini->docEntry($idName));
}
$fp->puts(CodeGen_PECL_Element_Ini::docFooter());
}
$fp->puts(" </para>\n");
$fp->puts("</section>\n");
$fp->puts($this->docEditorSettings());
$fp->close();
//
// configure.xml
//
// configure options and dependencies have their own file
$entities->puts("<!ENTITY reference.{$idName}.configure SYSTEM './{$idName}/configure.xml'>\n");
$fp = new CodeGen_Tools_FileReplacer("{$docdir}/{$idName}/configure.xml");
$fp->puts("<?xml version='1.0' encoding='iso-8859-1'?>\n<!-- " . '$' . "Revision: 1.1 \$ -->\n");
$fp->puts("\n <section id='{$idName}.requirements'>\n &reftitle.required;\n");
// TODO headers and libs are now "hidden" in $with
if (empty($this->libs) && empty($this->headers)) {
$fp->puts(" &no.requirement;\n");
} else {
// TODO allow custom text
if (isset($this->libs)) {
$libs = array();
foreach ($this->libs as $lib) {
$libs[] = $lib->getName();
}
$ies = count($libs) > 1 ? "ies" : "y";
$fp->puts("<para>This extension requires the following librar{$ies}: " . join(",", $libs) . "</para>\n");
}
if (isset($this->headers)) {
$headers = array();
foreach ($this->headers as $header) {
$headers[] = $header->getName();
}
$s = count($headers) > 1 ? "s" : "";
$fp->puts("<para>This extension requires the following header{$s}: " . join(",", $headers) . "</para>\n");
}
}
$fp->puts("\n </section>\n\n");
$fp->puts("\n <section id='{$idName}.install'>\n &reftitle.install;\n");
if (empty($this->with)) {
$fp->puts(" &no.install;\n");
} else {
foreach ($this->with as $with) {
if (isset($with->summary)) {
if (strstr($with->summary, "<para>")) {
$fp->puts($with->summary);
} else {
$fp->puts(" <para>\n" . rtrim($with->summary) . "\n </para>\n");
}
} else {
$fp->puts(" <para>Requires <literal>" . $with->getName() . "</literal></para>\n");
}
}
}
$fp->puts("\n </section>\n\n");
$fp->puts($this->docEditorSettings());
$fp->close();
//
$function_entities = array();
@mkdir("{$docdir}/{$idName}/functions");
foreach ($this->functions as $name => $function) {
$functionId = strtolower(str_replace("_", "-", $name));
$filepath = "{$idName}/functions/{$functionId}.xml";
$entity = "reference.{$idName}.functions.{$functionId}";
$function_entities[] = $entity;
$entities->puts("<!ENTITY {$entity} SYSTEM './{$filepath}'>\n");
$funcfile = new CodeGen_Tools_FileReplacer("{$docdir}{$filepath}");
$funcfile->puts($function->docEntry($idName));
$funcfile->puts($this->docEditorSettings(4));
$funcfile->close();
}
$entities->puts("<!ENTITY reference.{$idName}.functions SYSTEM './functions.xml'>\n");
$entities->close();
$functionsXml = new CodeGen_Tools_FileReplacer($docdir . "/functions.xml");
sort($function_entities);
foreach ($function_entities as $entity) {
$functionsXml->puts(" &{$entity};\n");
}
$functionsXml->close();
}