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 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. -``` +### 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` `` 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` `` 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` `` 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` `` 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` `` 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` `` 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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PACKAGEGenericIDEPEARPHP
FORMATxhtmlxmlxhtmlxhtml
bigxhtmlfunclistbigxhtmlbigxhtml
manpagejsonphpphp
phpchmchm
phpstubtocfeedtocfeed
sqlitemanpage
howto
pdf
bigpdf
kdevelop
epub
enhancedchm