Add phd docs files

phd/docbook-extensions.md

@@ -0,0 +1,30 @@
+[Customizing the rendering results](render-custom.php)
+
+[General DocBook extensions](ext-general.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)
+
+------
+
+# DocBook extensions
+
+## Table of Contents
+
+- [General DocBook extensions](ext-general.php)
+- [PEAR specific DocBook extensions](ext-pear.php)
+
+PhD has been tailored for PHP and PEAR manuals. To make writing documentation as easy as possible, some own tags have been added to the DTD.
+
+All extensions live in their own XML namespace "*phd:*" which resolves to `http:https://www.php.net/ns/phd`. When using one of the attributes or tags described here, remember to set the namespace:
+
+```
+xmlns:phd="http:https://www.php.net/ns/phd"
+```
+
+------
+
+[Customizing the rendering results](render-custom.php)
+
+[General DocBook extensions](ext-general.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)

phd/ext-general.md

@@ -0,0 +1,69 @@
+[DocBook extensions](docbook-extensions.php)
+
+[PEAR specific DocBook extensions](ext-pear.php)
+
+[DocBook extensions](docbook-extensions.php)
+
+------
+
+## General DocBook extensions
+
+The extensions listed here are available in all PhD themes and formats.
+
+## Manual chunking with "phd:chunk" (Attribute)
+
+PhD automatically chooses which sections, chapters or other tags get their own file (chunk) when using a chunked theme. Sometimes the result of this automatism is not optimal and you want to fine-tune it. The attribute "phd:chunk" is offered as solution by PhD.
+
+## Allowed values
+
+*phd:chunk* may have values *true* and *false*. They force the element to be chunked or not.
+
+## Allowed in
+
+*phd:chunk* may be used in every tag that accepts [» db.common.attributes](http:https://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributes).
+
+## Example
+
+```
+<?xml version="1.0" encoding="utf-8"?>
+<preface xmlns="http:https://docbook.org/ns/docbook"
+ xmlns:phd="http:https://www.php.net/ns/phd"
+ xml:id="preface"
+ phd:chunk="false"
+>
+ <info>
+ <title>Preface</title>
+ ..
+ </info>
+ ..
+</preface>
+```
+
+## Generating Table Of Contents: <phd:toc> (Tag)
+
+To manually insert a Table Of Contents (TOC) that creates a list of links to children elements of a specified tag.
+
+phd:toc-depth
+
+## Allowed in
+
+** is can be used everywhere ** is allowed.
+
+## Children
+
+You can add a title with **.
+
+## Attributes
+
+| Attribute name | Description | Default value |
+| -------------- | ---------------------------------------- | ------------- |
+| phd:element | ID of the element whose children shall be linked | *none* |
+| phd:toc-depth | Depth of the TOC/Number of levels | *1* |
+
+------
+
+[DocBook extensions](docbook-extensions.php)
+
+[PEAR specific DocBook extensions](ext-pear.php)
+
+[DocBook extensions](docbook-extensions.php)

phd/ext-pear.md

@@ -0,0 +1,69 @@
+[General DocBook extensions](ext-general.php)
+
+[Extending PhD](phd-extension.php)
+
+[DocBook extensions](docbook-extensions.php)
+
+------
+
+## PEAR specific DocBook extensions
+
+The DocBook extensions listed here are only available when using a PEAR theme.
+
+## Linking to PEAR API documentation: <phd:pearapi> (Tag)
+
+A large part of the PEAR manual is about packages and how to use them. Package authors often find they need to link to the API documentation of a specific method, variable or class of their package. To ease the linking process, the ** tag was introduced.
+
+You can let PhD automatically create the link text by just closing the tag, or specify the tag text via the tag's content.
+
+## Package links
+
+*phd:package* name is put into the attribute, any text:
+
+```
+<phd:pearapi phd:package="HTML_QuickForm"/>
+<phd:pearapi phd:package="HTML_QuickForm">some text</phd:pearapi>
+```
+
+[» HTML_QuickForm](http:https://pear.php.net/package/HTML_QuickForm/docs/latest/li_HTML_QuickForm.html) [» some text](http:https://pear.php.net/package/HTML_QuickForm/docs/latest/li_HTML_QuickForm.html)
+
+## Class links
+
+Class name as *phd:linkend* attribute value.
+
+```
+<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element"/>
+<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element">some text</phd:pearapi>
+```
+
+[» HTML_QuickForm_element](http:https://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html) [» some text](http:https://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html)
+
+## Class method links
+
+Class and method name as *phd:linkend* text, separated by a double colon.
+
+```
+<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element::setName"/>
+<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element::setName">some text</phd:pearapi>
+```
+
+[» HTML_QuickForm_element::setName()](http:https://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html#methodsetName) [» some text](http:https://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html#methodsetName)
+
+## Class variable links
+
+Class and variable name as *phd:linkend* text, separated by a double colon and a dollar sign before the variable name.
+
+```
+<phd:pearapi phd:package="Net_Geo" phd:linkend="Net_Geo::$cache_ttl"/>
+<phd:pearapi phd:package="Net_Geo" phd:linkend="Net_Geo::$cache_ttl">some text</phd:pearapi>
+```
+
+[» Net_Geo::$cache_ttl](http:https://pear.php.net/package/Net_Geo/docs/latest/Net_Geo/Net_Geo.html#var$cache_ttl) [» some text](http:https://pear.php.net/package/Net_Geo/docs/latest/Net_Geo/Net_Geo.html#var$cache_ttl)
+
+------
+
+[General DocBook extensions](ext-general.php)
+
+[Extending PhD](phd-extension.php)
+
+[DocBook extensions](docbook-extensions.php)

phd/getting-phd.md

@@ -0,0 +1,24 @@
+[About PhD](preface.php)
+
+[Installation](installation.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)
+
+------
+
+# Getting PhD
+
+## Table of Contents
+
+- [Installation](installation.php)
+
+You might find some other tutorials in the [links](links.php) section.
+
+------
+
+[About PhD](preface.php)
+
+[Installation](installation.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)
+

phd/index.md

@@ -0,0 +1,16 @@
+# PhD: The definitive guide to PHP's DocBook Rendering System
+
+ - [About PhD](preface.php)
+ - [Getting PhD](getting-phd.php)
+ - [Installation](installation.php)
+ - [Using PhD to render documentation](using-phd.php)
+ - [Rendering the PHP Documentation Sources](render-phpdoc.php)
+ - [Compiling the PhD guide](render-phd-guide.php)
+ - [Customizing the rendering results](render-custom.php)
+ - [DocBook extensions](docbook-extensions.php)
+ - [General DocBook extensions](ext-general.php)
+ - [PEAR specific DocBook extensions](ext-pear.php)
+ - [Extending PhD](phd-extension.php)
+ - [Writing an own syntax highlighter](phd-extension-highlighter.php)
+ - [Links](links.php)
+

phd/installation.md

@@ -0,0 +1,83 @@
+[Getting PhD](getting-phd.php)
+
+[Using PhD to render documentation](using-phd.php)
+
+[Getting PhD](getting-phd.php)
+
+------
+
+## Installation
+
+PhD is distributed via an own PEAR channel, `doc.php.net`. Using it is also the most easy way to get it.
+
+## Installation via PEAR
+
+> **Note**:
+>
+> You need a working [» PEAR installation](http:https://pear.php.net/manual/en/installation.php).
+>
+> 
+
+To install the latest version of PhD:
+
+```
+$ pear install doc.php.net/phd
+
+... downloading
+
+$ phd --version
+PhD Version: 1.0.0-stable
+PHP Version: 5.3.3
+Copyright(c) 2007-2010 The PHP Documentation Group
+
+```
+
+Installing the PhD Packages:
+
+```
+$ pear install doc.php.net/phd_php
+Starting to download PhD_PHP-1.0.0.tgz (18,948 bytes)
+[...]
+install ok: channel:https://doc.php.net/PhD_PHP-1.0.0
+
+$ pear install doc.php.net/phd_pear
+downloading PhD_PEAR-1.0.0.tgz ...
+[...]
+install ok: channel:https://doc.php.net/PhD_PEAR-1.0.0
+
+```
+
+That's it!
+
+## Installation from SVN
+
+To get the latest and greatest features that have not been released yet, you can use PhD from SVN.
+
+```
+$ svn checkout http:https://svn.php.net:/repository/phd/trunk phd
+... output
+
+pear install package.xml package_generic.xml package_php.xml package_pear.xml 
+[...]
+install ok: channel:https://doc.php.net/PhD-1.0.1
+install ok: channel:https://doc.php.net/PhD_Generic-1.0.1
+install ok: channel:https://doc.php.net/PhD_PHP-1.0.1
+install ok: channel:https://doc.php.net/PhD_PEAR-1.0.1
+bjori@jessica:/usr/src/php/svn/phd/trunk$ 
+
+$ phd --version
+PhD Version: phd-from-svn
+PHP Version: 5.3.3-dev
+Copyright(c) 2007-2010 The PHP Documentation Group
+
+```
+
+And now you're done.
+
+------
+
+[Getting PhD](getting-phd.php)
+
+[Using PhD to render documentation](using-phd.php)
+
+[Getting PhD](getting-phd.php)

phd/links.md

@@ -0,0 +1,18 @@
+[Writing an own syntax highlighter](phd-extension-highlighter.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)
+
+------
+
+# Links
+
+Some other articles for further reading. Latest are on top.
+
+- [» Setting up PhD on Windows](http:https://elizabethmariesmith.com/2009/02/setting-up-phd-on-windows/) by Elizabeth Marie Smith (PhD 0.4.5)
+- [» PhD 0.1RC1 released](http:https://bjori.blogspot.com/2007/10/phd-php-based-docbook-renderer-rc1.html) by Hannes Magnusson (PhD 0.1RC1)
+
+------
+
+[Writing an own syntax highlighter](phd-extension-highlighter.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)

phd/phd-extension-highlighter.md

@@ -0,0 +1,27 @@
+[Extending PhD](phd-extension.php)
+
+[Links](links.php)
+
+[Extending PhD](phd-extension.php)
+
+------
+
+## Writing an own syntax highlighter
+
+A syntax highlighter for PhD is nothing more than a simple PHP class that has two methods, a *factory* and *highlight*.
+
+*factory* is static and takes the format name (i.e. *pdf*, *xhtml*, *troff*) as only parameter. It returns the highlighter instance object for the given format. The method is called for each output format the documentation is rendered to.
+
+*highlight* takes three parameters, *text*, *role* and *format*. It is called whenever a piece of source code needs to be highlighted and expects the highlighted source code to be returned in whatever format the current rendering format is expected to be.
+
+Take a look at the provided highlighters, *phpdotnet\phd\Highlighter*, *phpdotnet\phd\Highlighter_GeSHi* and *phpdotnet\phd\Highlighter_GeSHi11x*. They will serve as good examples how to implement your own highlighter.
+
+Once you wrote your custom source code highlighting class, it's time to [try it out](render-custom.php#render-custom-highlighter).
+
+------
+
+[Extending PhD](phd-extension.php)
+
+[Links](links.php)
+
+[Extending PhD](phd-extension.php)

phd/phd-extension.md

@@ -0,0 +1,23 @@
+[PEAR specific DocBook extensions](ext-pear.php)
+
+[Writing an own syntax highlighter](phd-extension-highlighter.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)
+
+------
+
+# Extending PhD
+
+## Table of Contents
+
+- [Writing an own syntax highlighter](phd-extension-highlighter.php)
+
+Written in PHP, PhD is easy to hack on and easy to extend. It provides command line parameters to use custom code without changing PhD internals, like source code highlighters.
+
+------
+
+[PEAR specific DocBook extensions](ext-pear.php)
+
+[Writing an own syntax highlighter](phd-extension-highlighter.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)

phd/preface.md

@@ -0,0 +1,13 @@
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)
+
+[Getting PhD](getting-phd.php)
+
+[PhD: The definitive guide to PHP's DocBook Rendering System](index.php)
+
+------
+
+# About PhD
+
+PhD is PHP's very own DocBook 5 rendering system. It is used to convert the PHP Manual and PEAR Documentation into different output formats like XHTML, PDF, Man pages and CHM.
+
+The goal of PhD is to become a fast, general DocBook rendering system. At the moment of writing, PhD is already very fast: It can create the chunked version of PEAR's manual (some 3000 files) in less than a minute on a 2GHz system. It also renders the PHP and PEAR manual flawlessly. It does not support every DocBook 5 tag yet, and using it to render own DocBook files may need some tweaks.