Skip to content

Commit

Permalink
Update README (#141)
Browse files Browse the repository at this point in the history 
* Add references to the other parts of the documentation pipeline

* Remove section on formats

* Remove some options and reformat the remaining ones

* Add list of supported packages ans formats

---------

Co-authored-by: haszi <haszika80@gmail.com>
  • Loading branch information
@haszi
haszi and haszi authored Sep 11, 2024
1 parent 455a797 commit 8e2da87
Showing 1 changed file with 118 additions and 111 deletions.
229 changes: 118 additions & 111 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -72,125 +78,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
Expand Down Expand Up @@ -244,3 +183,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>

0 comments on commit 8e2da87

Please sign in to comment.