From 0ab118456d67d68aef524554f009d50890a59a3b Mon Sep 17 00:00:00 2001 From: haszi Date: Fri, 14 Jun 2024 18:16:35 +0200 Subject: [PATCH] Copy PhD guide into README (#132) * Copy PhD guide into README Convert PhD guide from XML to markdown. Copy markdown PhD guide into README. Change extension of README to .md. Remove url to non-existent page. Add section about language repositories. * Update wording and urls * Address review comments Remove all PEAR related sections. Remove the PhD guide related section. Remove the section about phd:chunk and phd:toc. Remove the v0.1RC1 release announcement link. * Minor rewrite Replace calling the phd command with running phd/render.php with php. Remove duplicate 'Using PhD' section. Remove a few unnecessary sentences. Rewrite a few sentences. Add header for the rendering options section. --------- Co-authored-by: haszi --- README | 48 ----------- README.md | 238 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 238 insertions(+), 48 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 3f958ab4..00000000 --- a/README +++ /dev/null @@ -1,48 +0,0 @@ -PhD - PHP DocBook -Copyright(c) 2007-2018 The PHP Documentation Team - -Installing the PhD renderer: - From a PEAR channel: - pear install doc.php.net/phd - - To install the PHP Package: - pear install doc.php.net/phd_php - - To install the PEAR Package: - pear install doc.php.net/phd_pear - - To see all available packages: - pear remote-list -c doc.php.net - - From GIT: - Note: Do not install anything from PEAR above. - - git clone https://github.com/php/phd.git - cd phd - pear install package.xml package_generic.xml - - To install the standalone Packages: - for i in package_*.xml; do pear install $i; done - -Running from the source, assuming that the PHP documentation tree is at -dev/php/phpdoc/doc-base and dev/php/phpdoc/en: - - cd dev/php - git clone https://github.com/php/phd.git - cd phpdoc - php doc-base/configure.php --disable-segfault-error - php ../phd/render.php --docbook doc-base/.manual.xml --output=/tmp/docs --package PHP --format xhtml - -Requirements: - - PHP 7.1 - - DOM, libXML2, XMLReader and SQLite3. - -After installing PhD you can use the `phd` command -to render the documentations. To see a list of available packages/formats -use the `phd -l` command. By default `phd` use ./output for the rendered files. - -The `phd` command optionally takes more arguments. -For information about those arguments please type `phd -h` - - -- The PHP Documentation team diff --git a/README.md b/README.md new file mode 100644 index 00000000..ec17fae4 --- /dev/null +++ b/README.md @@ -0,0 +1,238 @@ +# PhD - PHP DocBook + +## About PhD + +PhD is PHP's DocBook rendering system +which is used to convert the PHP Manual into different output formats. + + +## Requirements + +- PHP 8.0+ +- DOM, libXML2, XMLReader and SQLite3. + + +## Rendering the PHP Documentation Sources + +To render the PHP documentation, you will need to clone the +documentation source files, `doc-base` and PhD. + +To get the PHP documentation sources, clone them from the official GitHub +repositories. To clone the English documentation: + +```shell +$ git clone https://github.com/php/doc-en en +``` + +
+ List of languages/repositories + + - [Brazilian Portugues](https://github.com/php/doc-pt_br) (doc-pt_br) + - [Chinese(Simplified)](https://github.com/php/doc-zh) (doc-zh) + - [English](https://github.com/php/doc-en) (doc-en) + - [French](https://github.com/php/doc-fr) (doc-fr) + - [German](https://github.com/php/doc-de) (doc-de) + - [Italian](https://github.com/php/doc-it) (doc-it) + - [Japanese](https://github.com/php/doc-ja) (doc-ja) + - [Polish](https://github.com/php/doc-pl) (doc-pl) + - [Romanian](https://github.com/php/doc-ro) (doc-ro) + - [Russian](https://github.com/php/doc-ru) (doc-ru) + - [Spanish](https://github.com/php/doc-es) (doc-es) + - [Turkish](https://github.com/php/doc-tr) (doc-tr) + - [Ukrainian](https://github.com/php/doc-uk) (doc-uk) +

+ +To check the documentation and combine it into one file, +you need to clone PHP's `doc-base` repository + +```shell +$ git clone https://github.com/php/doc-base +``` + +and run `configure.php` + +```shell +$ php doc-base/configure.php +``` + +which will generate a `.manual.xml` file in the `doc-base` directory. + +To render the documentation in `xhtml` format +into the default `./output/` directory: + +```shell +$ php phd/render.php -d doc-base/.manual.xml -P PHP -f xhtml +``` + + +## PhD's rendering options + +Let's take a closer look at PhD and see what capabilities are available to us. + +```shell +$ php phd/render.php --help +PhD version: 1.1.12 +Copyright(c) 2007-2024 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. +``` + +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. + +```shell +$ php phd/render.php --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 +``` + +To select a format and package, you must use the `-f [formatName]` and +`-P [packageName]` options. + +E.g.: to generate the documentation in the same format used on `php.net`, +use the PHP package's `php` format. +```shell +$ php phd/render.php -d .manual.xml -P PHP -f php +``` + + +## Syntax highlighting + +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. + +```xml + +]]> +``` + +By default, PhD uses the source code highlighter that is built into PHP +itself which is only able to highlight PHP code. + +If your documentation contains other types of source code or markup, +you can write a custom syntax highlighter. + + +### Writing a custom syntax highlighter + +A syntax highlighter for PhD is nothing more than a simple PHP class +that has two methods: `factory` and `highlight`. + +`factory` is static, takes the format name (i.e. `pdf`, `xhtml`, +`troff`) as its only parameter and 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 the format +of the current rendering format. + +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 +on how to implement your own highlighter. + +Once you wrote your custom source code highlighting class, it's time to +[try it out](#syntax-highlighting).