diff --git a/phd/docbook-extensions.md b/phd/docbook-extensions.md new file mode 100644 index 0000000..391cc3a --- /dev/null +++ b/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://www.php.net/ns/phd`. When using one of the attributes or tags described here, remember to set the namespace: + +``` +xmlns:phd="http://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) \ No newline at end of file diff --git a/phd/ext-general.md b/phd/ext-general.md new file mode 100644 index 0000000..996637e --- /dev/null +++ b/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://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributes). + +## Example + +``` + + + + Preface + .. + + .. + +``` + +## Generating Table Of Contents: (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) \ No newline at end of file diff --git a/phd/ext-pear.md b/phd/ext-pear.md new file mode 100644 index 0000000..2f3a33f --- /dev/null +++ b/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: (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: + +``` + +some text +``` + +[» HTML_QuickForm](http://pear.php.net/package/HTML_QuickForm/docs/latest/li_HTML_QuickForm.html) [» some text](http://pear.php.net/package/HTML_QuickForm/docs/latest/li_HTML_QuickForm.html) + +## Class links + +Class name as *phd:linkend* attribute value. + +``` + +some text +``` + +[» HTML_QuickForm_element](http://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html) [» some text](http://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. + +``` + +some text +``` + +[» HTML_QuickForm_element::setName()](http://pear.php.net/package/HTML_QuickForm/docs/latest/HTML_QuickForm/HTML_QuickForm_element.html#methodsetName) [» some text](http://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. + +``` + +some text +``` + +[» Net_Geo::$cache_ttl](http://pear.php.net/package/Net_Geo/docs/latest/Net_Geo/Net_Geo.html#var$cache_ttl) [» some text](http://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) \ No newline at end of file diff --git a/phd/getting-phd.md b/phd/getting-phd.md new file mode 100644 index 0000000..619fe36 --- /dev/null +++ b/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) + diff --git a/phd/index.md b/phd/index.md new file mode 100644 index 0000000..476f13f --- /dev/null +++ b/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) + diff --git a/phd/installation.md b/phd/installation.md new file mode 100644 index 0000000..5be8b18 --- /dev/null +++ b/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://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://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://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://svn.php.net:/repository/phd/trunk phd +... output + +pear install package.xml package_generic.xml package_php.xml package_pear.xml +[...] +install ok: channel://doc.php.net/PhD-1.0.1 +install ok: channel://doc.php.net/PhD_Generic-1.0.1 +install ok: channel://doc.php.net/PhD_PHP-1.0.1 +install ok: channel://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) \ No newline at end of file diff --git a/phd/links.md b/phd/links.md new file mode 100644 index 0000000..1128229 --- /dev/null +++ b/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://elizabethmariesmith.com/2009/02/setting-up-phd-on-windows/) by Elizabeth Marie Smith (PhD 0.4.5) +- [» PhD 0.1RC1 released](http://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) \ No newline at end of file diff --git a/phd/phd-extension-highlighter.md b/phd/phd-extension-highlighter.md new file mode 100644 index 0000000..0317e23 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/phd/phd-extension.md b/phd/phd-extension.md new file mode 100644 index 0000000..cdb47f9 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/phd/preface.md b/phd/preface.md new file mode 100644 index 0000000..002154b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/phd/render-custom.md b/phd/render-custom.md new file mode 100644 index 0000000..6ab22fb --- /dev/null +++ b/phd/render-custom.md @@ -0,0 +1,67 @@ +[Compiling the PhD guide](render-phd-guide.php) + +[DocBook extensions](docbook-extensions.php) + +[Using PhD to render documentation](using-phd.php) + +------ + +## Customizing the rendering results + +PhD lets you specify a number of options to customize the generated documentation files. The following sections describe some of them. + +## Source code highlighter + +Part of the documentation of programming languages is source code examples. PhD is able to colorize the source code of many types of source code with the help of *highlighters*. + +To utilize syntax highlighting, your opening ** tags need a *role* attribute describing the type of source code. Examples are *php*, *html* and *python*. + +> **Note**: +> +> PhD currently only highlights the code if it is embedded in a *CDATA* section. +> +> + +**Example #1 A programlisting tag with a role** + +``` + +``` + +``` +]]> +``` + +By default, PhD uses the source code highlighter that is built into PHP itself. It is only able to highlight PHP code and nothing else. + +If your documentation contains other types of source code or markup, like XML, HTML, Javascript or any other language, you should try the [» GeSHi](http://qbnz.com/highlighter/) highlighter that is shipped with PhD: + +1. Install GeSHi from the MediaWiki PEAR channel: + + ``` + $ pear channel-discover mediawiki.googlecode.com/svn + $ pear install mediawiki/geshi + ``` + +2. Use the GeSHi syntax highlighting class when rendering your documentation: + + ``` + $ phd -g 'phpdotnet\phd\Highlighter_GeSHi' -d phd-guide.xml + ``` + + ​ + +If you have GeSHi version 1.1.x installed, you should use the *phpdotnet\phd\Highlighter_GeSHi11x* highlighter, which is adapted to GeSHi's new API. + +Apart from using the highlighter shipped with PhD, you can [build your own highlighters](phd-extension-highlighter.php). + +------ + +[Compiling the PhD guide](render-phd-guide.php) + +[DocBook extensions](docbook-extensions.php) + +[Using PhD to render documentation](using-phd.php) \ No newline at end of file diff --git a/phd/render-phd-guide.md b/phd/render-phd-guide.md new file mode 100644 index 0000000..b93d7ff --- /dev/null +++ b/phd/render-phd-guide.md @@ -0,0 +1,37 @@ +[Rendering the PHP Documentation Sources](render-phpdoc.php) + +[Customizing the rendering results](render-custom.php) + +[Using PhD to render documentation](using-phd.php) + +------ + +## Compiling the PhD guide + +The PhD guide is this manual you are reading currently. It lives in PhD's SVN repository under docs/phd-guide/phd-guide.xml. If you installed PhD from SVN, you already have it. Otherwise, get it: + +``` +$ svn checkout http://svn.php.net:/repository/phd/trunk/docs/phd-guide +U phd/docs/phd-guide/phd-guide.xml + +``` + +Now you have everything you need. Just type + +``` +$ cd phd/docs/phd-guide/ +$ phd -f bigxhtml -d phd-guide.xml + +``` + +There should be an .html file in the directory now. View it with a browser! + +That's all to say. This way you can render your own docbook files, too. + +------ + +[Rendering the PHP Documentation Sources](render-phpdoc.php) + +[Customizing the rendering results](render-custom.php) + +[Using PhD to render documentation](using-phd.php) \ No newline at end of file diff --git a/phd/render-phpdoc.md b/phd/render-phpdoc.md new file mode 100644 index 0000000..ae32669 --- /dev/null +++ b/phd/render-phpdoc.md @@ -0,0 +1,172 @@ +[Using PhD to render documentation](using-phd.php) + +[Compiling the PhD guide](render-phd-guide.php) + +[Using PhD to render documentation](using-phd.php) + +------ + +## Rendering the PHP Documentation Sources + +> # Getting the PHP Documentation Sources +> +> To get the PHP documentation sources, simply [» check them out from SVN](http://wiki.php.net/doc/scratchpad/howto/checkout) with the following command. +> +> ``` +> $ svn co http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc +> ... output +> +> ``` +> +> To prepare the documentation, **cd** to the phpdoc directory, and run configure.php. +> +> ``` +> $ php doc-base/configure.php +> ``` +> +> This process will generate a .manual.xml file in the current directory, which is what we need for building the docs. Now we're ready to proceed with running PhD to generate the PHP docs. + +To quickly become familiar with using PhD, you can download the PHP documentation sources and render those.Running PhD to render the docs is surprisingly simple, so we'll start with that. + +``` +$ phd -d doc-base/.manual.xml -P PHP +... status messages + +``` + +After a running for a few moments, PhD will generate all the output formats of the PHP Package into *output/*. + +So now that you've seen the fruits of your labor, let's take a closer look at PhD and see what capabilities are available to us. + +``` +$ phd --help +PhD version: 1.1.6 +Copyright(c) 2007-2013 The PHP Documentation Group + + -v + --verbose Adjusts the verbosity level + -f + --format The build format to use + -P + --package The package to use + -I + --noindex Do not index before rendering but load from cache + (default: false) + -M + --memoryindex Do not save indexing into a file, store it in memory. + (default: false) + -r + --forceindex Force re-indexing under all circumstances + (default: false) + -t + --notoc Do not rewrite TOC before rendering but load from + cache (default: false) + -d + --docbook The Docbook file to render from + -x + --xinclude Process XML Inclusions (XInclude) + (default: false) + -p + --partial The ID to render, optionally skipping its children + chunks (default to true; render children) + -s + --skip The ID to skip, optionally skipping its children + chunks (default to true; skip children) + -l + --list Print out the supported packages and formats + -o + --output The output directory (default: .) + -F filename + --outputfilename filename Filename to use when writing standalone formats + (default: -.) + -L + --lang The language of the source file (used by the CHM + theme). (default: en) + -c + --color Enable color output when output is to a terminal + (default: true) + -C + --css Link for an external CSS file. + -g + --highlighter Use custom source code highlighting php class + -V + --version Print the PhD version information + -h + --help This help + -e + --ext The alternative filename extension to use, + including the dot. Use 'false' for no extension. + -S + --saveconfig Save the generated config (default: false). + + -Q + --quit Don't run the build. Use with --saveconfig to + just save the config. + -k + --packagedir Use an external package directory. + + +Most options can be passed multiple times for greater effect. + +``` + +As you can see, there are plenty of options to look into in PhD. The most important options are those which allow you to select a format and package to output your documentation to. + +``` +$ phd --list +Supported packages: + Generic + xhtml + bigxhtml + manpage + IDE + xml + funclist + json + php + phpstub + PEAR + xhtml + bigxhtml + php + chm + tocfeed + PHP + xhtml + bigxhtml + php + howto + manpage + pdf + bigpdf + kdevelop + chm + tocfeed + epub + enhancedchm + +``` + +> **Note**: +> +> The format packages are provided by separate PEAR packages (doc.php.net/PhD_Generic, doc.php.net/PhD_IDE, doc.php.net/PhD_PEAR and doc.php.net/PhD_PHP) where only the Generic is installed by default. +> +> + +You can tell by the output of the *--list* option that PhD can also be used to render the docs as a PDF file, or as Unix Man Pages. + +To select a format and package, you must use the *-f [formatName]* and *-P [packageName]* options. + +``` +$ phd -f manpage -P PHP -d .manual.xml +``` + +This command will output the documentation for PHP functions in the Unix Man page format. + +------ + +[Using PhD to render documentation](using-phd.php) + +[Compiling the PhD guide](render-phd-guide.php) + +[Using PhD to render documentation](using-phd.php) \ No newline at end of file diff --git a/phd/using-phd.md b/phd/using-phd.md new file mode 100644 index 0000000..e4e0f81 --- /dev/null +++ b/phd/using-phd.md @@ -0,0 +1,23 @@ +[Installation](installation.php) + +[Rendering the PHP Documentation Sources](render-phpdoc.php) + +[PhD: The definitive guide to PHP's DocBook Rendering System](index.php) + +------ + +# Using PhD to render documentation + +## Table of Contents + +- [Rendering the PHP Documentation Sources](render-phpdoc.php) +- [Compiling the PhD guide](render-phd-guide.php) +- [Customizing the rendering results](render-custom.php) + +------ + +[Installation](installation.php) + +[Rendering the PHP Documentation Sources](render-phpdoc.php) + +[PhD: The definitive guide to PHP's DocBook Rendering System](index.php) \ No newline at end of file diff --git a/www/.htaccess b/www/.htaccess index f7e7d16..ee6e108 100644 --- a/www/.htaccess +++ b/www/.htaccess @@ -1,3 +1,6 @@ +# http://doc.php.io +# https://github.com/php/web-doc + RewriteEngine On # tutorial rewrites @@ -6,6 +9,9 @@ RewriteRule ^(((.+)/)+)?tutorial$ /$1tutorial/ [L,R=301] RewriteRule ^tutorial/$ /tutorial.php?chapter=intro [L] RewriteRule ^tutorial/([a-z\-]*).php$ /tutorial.php?chapter=$1 [L] +RewriteRule ^phd/docs/$ /phd-docs.php?chapter=index [L] +RewriteRule ^phd/docs/([a-z\-]*).php$ /phd-docs.php?chapter=$1 [L] + RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ /redirect.php diff --git a/www/favicon.ico b/www/favicon.ico new file mode 100644 index 0000000..f095b7f Binary files /dev/null and b/www/favicon.ico differ diff --git a/www/phd-docs.php b/www/phd-docs.php new file mode 100644 index 0000000..3a2bc3f --- /dev/null +++ b/www/phd-docs.php @@ -0,0 +1,25 @@ +text($content); + +site_footer();