mirror of
https://github.com/php/web-doc.git
synced 2025-08-10 02:56:24 +00:00
65 lines
2.7 KiB
Markdown
65 lines
2.7 KiB
Markdown
# Editing manual sources
|
|
|
|
## Introduction
|
|
Before making any changes to the manual - either English version ore
|
|
translation, make sure you read [style guidelines](style.php)!
|
|
|
|
## Editing existing documentation
|
|
Simply open the files and edit them.
|
|
|
|
## Adding new documentation
|
|
When adding new functions or methods, there are a couple of options.
|
|
|
|
### Option A: Generating files using docgen
|
|
This is preferred way to generate files for new extensions, classes, functions
|
|
or methods using [`docgen`][docgen]. The script is found in the [doc-base][doc-base]
|
|
repository and uses reflection to generate documentation (DocBook) files.
|
|
|
|
### Option B: Copy skeleton files
|
|
This involves copying the skeleton files into the correct location:
|
|
```
|
|
cp /phpdoc/RFC/skeletons/method.xml classname/methodname.xml #for new methods
|
|
cp /phpdoc/RFC/skeletons/function.xml functions/functionname.xml #for new functions
|
|
```
|
|
|
|
Note: *classname*, *methodname* and *functionname* are lowercased names of the
|
|
class, method, or function, respectively, not a literal file name.
|
|
|
|
Remember the extension folder [structure](structure.php) when copying those files.
|
|
|
|
## Translating documentation
|
|
The translation process is described in the [translating chapter](translating.php).
|
|
|
|
## Validating your changes
|
|
Every time you make changes to documentation sources (both English or translation),
|
|
you have to validate your changes to ensure that the manual still builds without error.
|
|
The necessary [configure.php][configure.php] script is distributed with the
|
|
[doc-base][doc-base] repository, so you should already have it. All you have
|
|
to do to validate changes is run configure.php:
|
|
```
|
|
$ cd phpdoc
|
|
$ php configure.php --with-lang={LANG}
|
|
```
|
|
If your language is English you can omit the `with-lang` argument. When the above
|
|
outputs something like "All good. Saving .manual.xml… done." then you know it validates.
|
|
You can commit your changes now.
|
|
|
|
## Commit changes
|
|
If you have the appropriate [commit karma][karma], you can commit your modified files.
|
|
|
|
## Viewing changes online
|
|
Documentation is built every night, at around 23:00 CST, then synced out to the
|
|
website mirrors. However, there is a special mirror at [docs.php.net][docs] - where
|
|
the manual is updated from sources every four hours. If any errors occurred, a message
|
|
will be delivered to the appropriate mailinglist (`doc-{LANG}@lists.php.net`).
|
|
|
|
Read more about manual builds in the [builds appendix](builds.php).
|
|
|
|
The next chapter contains [style guidelines](style.php) that you are obliged to
|
|
follow. Read them carefully.
|
|
|
|
[docgen]: https://github.com/php/doc-base/tree/master/scripts/docgen
|
|
[doc-base]: https://github.com/php/doc-base/
|
|
[configure.php]: https://github.com/php/doc-base/blob/master/configure.php
|
|
[docs]: http://docs.php.net/
|