diff --git a/README.md b/README.md index ec17fae4..f245b036 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,12 @@ PhD is PHP's DocBook rendering system which is used to convert the PHP Manual into different output formats. +If you would like to contribute to PHP's documentation please refer to the +[contribution guidelines](https://github.com/php/doc-base/blob/master/CONTRIBUTING_DOCS.md). + +If you would like to know more about how PHP's documentation is built +and what the different parts of its pipeline are, please refer to the +[documentation overview](https://github.com/php/doc-base/blob/master/OVERVIEW.md). ## Requirements @@ -64,125 +70,58 @@ into the default `./output/` directory: $ php phd/render.php -d doc-base/.manual.xml -P PHP -f xhtml ``` +`xhtml` files are standalone files that can be opened directly in a browser. +To render the documentation in the same `php` format used on the `php.net` website: + +```shell +$ php phd/render.php -d doc-base/.manual.xml -P PHP -f php +``` + +Please refer to the appropriate section of the +[contribution guidelines](https://github.com/php/doc-base/blob/master/CONTRIBUTING_DOCS.md#more-complex-changes--building-the-php-documentation) +on setting up a local mirror of the PHP documentation. ## PhD's rendering options -Let's take a closer look at PhD and see what capabilities are available to us. +The following sections list PhD's the most frequently used options. +To see the list of all options run PhD with the `-h` \ `--help` option. -```shell -$ php phd/render.php --help -PhD version: 1.1.12 -Copyright(c) 2007-2024 The PHP Documentation Group - - -v - --verbose <int> Adjusts the verbosity level - -f <formatname> - --format <formatname> The build format to use - -P <packagename> - --package <packagename> 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 <filename> - --docbook <filename> The Docbook file to render from - -x - --xinclude Process XML Inclusions (XInclude) - (default: false) - -p <id[=bool]> - --partial <id[=bool]> The ID to render, optionally skipping its children - chunks (default to true; render children) - -s <id[=bool]> - --skip <id[=bool]> The ID to skip, optionally skipping its children - chunks (default to true; skip children) - -l - --list Print out the supported packages and formats - -o <directory> - --output <directory> The output directory (default: .) - -F filename - --outputfilename filename Filename to use when writing standalone formats - (default: <packagename>-<formatname>.<formatext>) - -L <language> - --lang <language> The language of the source file (used by the CHM - theme). (default: en) - -c <bool> - --color <bool> Enable color output when output is to a terminal - (default: true) - -C <filename> - --css <filename> Link for an external CSS file. - -g <classname> - --highlighter <classname> Use custom source code highlighting php class - -V - --version Print the PhD version information - -h - --help This help - -e <extension> - --ext <extension> The alternative filename extension to use, - including the dot. Use 'false' for no extension. - -S <bool> - --saveconfig <bool> 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. -``` +### Input -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. +`-d` \ `--docbook` `<filename>` The Docbook file to render -```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 -``` +`-p` \ `--partial` `<id[=bool]>` Partial rendering: the ID to render, optionally skipping its children chunks (default to true; render children) -To select a format and package, you must use the `-f [formatName]` and -`-P [packageName]` options. +`-s` \ `--skip` `<id[=bool]>` Partial rendering: the ID to skip, optionally skipping its children chunks (default to true; skip children) -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 -``` +### Output + +`-P` \ `--package` `<packagename>` The package to use. +If a package is specified without a format the input file is rendered +in every format of the package. +For a list of supported packages, see the list of +[Supported output formats](#supported-output-formats). + +`-f` \ `--format` `<formatname>` The build format to use. +If no package is specified, the appropriate format of the `Generic` package is used. +For a list of supported formats, see the list of +[Supported output formats](#supported-output-formats) + +`-o` \ `--output` `<directory>` The output directory (default: .) + +### Indexing + +`-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. (default: false) + +### Information + +`-h` \ `--help` Lists all available options. + +`-l` \ `--list` Lists all supported packages and formats. ## Syntax highlighting @@ -236,3 +175,71 @@ 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). + +## Supported output formats + +PhD currently supports the following output formats: + +<table> + <tr> + <td><b>PACKAGE</b></td> + <td><b>Generic</b></td> + <td><b>IDE</b></td> + <td><b>PEAR</b></td> + <td><b>PHP</b></td> + </tr> + <tr> + <td rowspan="12"><b>FORMAT</b></td> + <td>xhtml</td> + <td>xml</td> + <td>xhtml</td> + <td>xhtml</td> + </tr> + <tr> + <td>bigxhtml</td> + <td>funclist</td> + <td>bigxhtml</td> + <td>bigxhtml</td> + </tr> + <tr> + <td>manpage</td> + <td>json</td> + <td>php</td> + <td>php</td> + </tr> + <tr> + <td rowspan="9"></td> + <td>php</td> + <td>chm</td> + <td>chm</td> + </tr> + <tr> + <td>phpstub</td> + <td>tocfeed</td> + <td>tocfeed</td> + </tr> + <tr> + <td>sqlite</td> + <td rowspan="7"></td> + <td>manpage</td> + </tr> + <tr> + <td rowspan="6"></td> + <td>howto</td> + </tr> + <tr> + <td>pdf</td> + </tr> + <tr> + <td>bigpdf</td> + </tr> + <tr> + <td>kdevelop</td> + </tr> + <tr> + <td>epub</td> + </tr> + <tr> + <td>enhancedchm</td> + </tr> +</table>