From a88f68d6f8117dda845c2f5121fea3dd2942ace2 Mon Sep 17 00:00:00 2001 From: haszi Date: Sun, 16 Jun 2024 22:07:57 +0200 Subject: [PATCH 1/4] Add references to the other parts of the documentation pipeline --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index ec17fae4..c5f66f64 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,6 +70,16 @@ 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 From 6fc5d97a1b43614d8e28f91c0b1bc9ccaf5d9f85 Mon Sep 17 00:00:00 2001 From: haszi Date: Sun, 16 Jun 2024 22:09:24 +0200 Subject: [PATCH 2/4] Remove section on formats --- README.md | 47 ----------------------------------------------- 1 file changed, 47 deletions(-) diff --git a/README.md b/README.md index c5f66f64..a5a1c37c 100644 --- a/README.md +++ b/README.md @@ -153,53 +153,6 @@ Copyright(c) 2007-2024 The PHP Documentation Group --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 From b719a3aed9e2188892062cd19b03896de53be8e4 Mon Sep 17 00:00:00 2001 From: haszi Date: Sun, 23 Jun 2024 19:34:23 +0200 Subject: [PATCH 3/4] Remove some options and reformat the remaining ones --- README.md | 102 ++++++++++++++++++------------------------------------ 1 file changed, 34 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index a5a1c37c..f362cfae 100644 --- a/README.md +++ b/README.md @@ -83,75 +83,41 @@ 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 + +`-d` \ `--docbook` `` The Docbook file to render + +`-p` \ `--partial` `` Partial rendering: the ID to render, optionally skipping its children chunks (default to true; render children) + +`-s` \ `--skip` `` Partial rendering: the ID to skip, optionally skipping its children chunks (default to true; skip children) + +### 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. + +`-f` \ `--format` `` The build format to use. +If no package is specified, the appropriate format of the `Generic` package is used. + +`-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 From 657b1a1ad246c10bdbba384f4163580644bdd794 Mon Sep 17 00:00:00 2001 From: haszi Date: Sun, 28 Jul 2024 17:16:49 +0200 Subject: [PATCH 4/4] Add list of supported packages ans formats --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/README.md b/README.md index f362cfae..f245b036 100644 --- a/README.md +++ b/README.md @@ -99,9 +99,13 @@ To see the list of all options run PhD with the `-h` \ `--help` option. `-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: .) @@ -171,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