diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md deleted file mode 100644 index 3b584179b..000000000 --- a/CONTRIBUTING_DOCS.md +++ /dev/null @@ -1,217 +0,0 @@ -# Contributing to the PHP Documentation - -You can easily contribute to the PHP documentation -by either [reporting a bug](#report-a-bug) -or by fixing one by [submitting a pull request](#submit-a-pull-request). -As all the repositories are hosted on GitHub, -you will need a GitHub account to do either of these. - -## Report a Bug - -If you have found a bug on any of the PHP documentation pages, -you can file a bug report by doing the following: - -- click the "Report a Bug" link in the "Improve This Page" section - on the bottom of the page -- log into GitHub -- add a short description of the bug in the title textbox -- add all necessary details to the description textarea -- click the "Submit new issue" button to file your bug report - -## Submit a Pull Request - -There are two ways to make changes to the documentation: -- make [minor changes](#minor-changes) by editing files on GitHub -- make [more complex changes](#more-complex-changes--building-the-php-documentation) - and validate/build the documentation locally on your computer - -## Minor changes - -To make trivial changes (typos, shorter wording changes or adding/removing short segments) -all one needs is a web-browser and a GitHub account and doing the following: - -- click the "Submit a Pull Request" link in the "Improve This Page" section - on the bottom of the documentation page -- log into GitHub -- fork the repository (if you have not forked it already) -- make changes -- click the "Commit changes" button -- add a commit message (short description of the change) into the "Commit message" textbox -- write a longer description in the "Extended description" textarea, if needed -- click the "Propose changes" button -- review your changes and click "Create pull request" button - -The repository will run a few basic checks on the changes -(e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.) -and your PR is ready to be discussed with and merged by the maintainers. - -## More Complex Changes / Building the PHP documentation - -To build and view the documentation after making more extensive changes -(e.g. adding entire sections or files), you will need to -[clone some of the tooling](#set-up-a-development-environment) -(doc-base, phd and possibly web-php) -in addition to the language repository you want to -[make the changes](#make-changes-to-the-documentation) to. -You need to [validate the changes](#validate-the-documentation) -and you can (but do not have to) [render the documentation](#render-the-documentation) -before you [open a PR](#commit-changes-and-open-a-pr). - -If you'd like to know more about what each repository is -and/or how PHP's documentation is built please refer to -this [overview](https://github.com/php/doc-base/blob/master/OVERVIEW.md). - -### Requirements - -Following this guide to make changes to and build the documentation has the following dependencies: -- PHP 8.0+ with the DOM, libXML2, XMLReader and SQLite3 extensions -- Git -- an IDE or a text editor - -### Set up a development environment - -#### Basic setup - -To start working on the English documentation, you need to fork it on Github -and clone it, doc-base (for validating the XML files) and PhD (for rendering the files). - -```shell -git clone https://github.com// en -git clone https://github.com/php/doc-base -git clone https://github.com/php/phd -cd en -git remote add upstream https://github.com/php/doc-en -``` -where `` and `` needs to be replaced by -your GitHub username and the name of your for of the English documentation respectively. -Please note that the English documentation has to be cloned into the `en` directory. - -To clone any of the translations, replace `doc-en en` at the end of the first line -with the translation you would like to clone -(e.g. `doc-pt_br` for the Brazilian documentation). -As an example, the following shows how to set up the Brazilian documentation: - -```shell -git clone https://github.com//doc-pt_br -git clone https://github.com/php/doc-base -git clone https://github.com/php/phd -cd doc-pt_br -git remote add upstream https://github.com/php/doc-pt_br -``` -where `` needs to be replaced by your GitHub username. - -
- List of languages/repositories - - - [Brazilian Portugues](https://github.com/php/doc-pt_br) (doc-pt_br) - - [Chinese(Simplified)](https://github.com/php/doc-zh) (doc-zh) - - [English](https://github.com/php/doc-en) (doc-en) - - [French](https://github.com/php/doc-fr) (doc-fr) - - [German](https://github.com/php/doc-de) (doc-de) - - [Italian](https://github.com/php/doc-it) (doc-it) - - [Japanese](https://github.com/php/doc-ja) (doc-ja) - - [Polish](https://github.com/php/doc-pl) (doc-pl) - - [Romanian](https://github.com/php/doc-ro) (doc-ro) - - [Russian](https://github.com/php/doc-ru) (doc-ru) - - [Spanish](https://github.com/php/doc-es) (doc-es) - - [Turkish](https://github.com/php/doc-tr) (doc-tr) - - [Ukrainian](https://github.com/php/doc-uk) (doc-uk) -
- -#### Setting up a local mirror - -If you would like to setup a local mirror of the documentation -or you would just like to see how your changes will look like online: - -```shell -git clone https://github.com/php/web-php -cd web-php/manual -rm -rf en -ln -s ../../output/php-web en -``` - -where `../../output/php-web` is the directory the PhD generated .php files are saved at, -relative to the `web-php/manual` directory. - -On Windows: - -```shell -git clone https://github.com/php/web-php -cd \your\path\to\web-php\manual\ -rmdir /S en -mklink /D en \your\path\to\output\web-php -``` - -where `\your\path\to\output\web-php` is the directory the PhD generated .php files are saved at, -relative to the `\your\path\to\web-php\manual\` directory. - -#### Using your local mirror - -You can view the documentation by using any web server -but one of the simplest ways is to use PHP's built-in web server: - -```shell -cd web-php -php -S localhost:8080 .router.php -``` - -where `web-php` is the directory web-php has been cloned into. - -The manual is now available from http://localhost:8080/manual/en/ in your browser. - -### Make changes to the documentation - -Make your changes keeping in mind the [style guidelines](http://doc.php.net/tutorial/style.php). - -### Validate the documentation - -To validate the English documentation (located in the directory `en`), run -```shell -php doc-base/configure.php -``` - -To validate any other documentation, run -```shell -php doc-base/configure.php --with-lang=doc-lang -``` -where `doc-lang` is the name of your language's repository -and the corresponding directory (eg. `doc-de` for German). - -*Please note that all validation errors have to be corrected -before opening a PR.* - -### Render the documentation - -To render the documentation in xhtml format (can be viewed without a web server), run -```shell -php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml -``` - -To render the documentation in php format (needs a web server and web-php), run -```shell -php phd/render.php --docbook doc-base/.manual.xml --package PHP --format php -``` - -### Commit changes and open a PR - -- commit your changes -- push to your fork -- open a PR in the appropriate language repository - -Once you open a PR, the documentation repository will run a few basic checks on the changes -(e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.) -and your PR is ready to be discussed with and merged by the maintainers. - -## Additional information - -For additional information on contributing to the documentation refer to: - -- the [Adding new documentation](http://doc.php.net/tutorial/editing.php) - section of the "Editing manual sources" page -- the [Files structure](http://doc.php.net/tutorial/structure.php) - section of the "Manual sources structure" page -- the [Translating documentation](http://doc.php.net/tutorial/translating.php) page -- the [Style guidelines](http://doc.php.net/tutorial/style.php) page -- the [FAQ](http://doc.php.net/tutorial/faq.php) page -- the [Why we care about whitespace](http://doc.php.net/tutorial/whitespace.php) page -- doc-base's [README](https://github.com/php/doc-base/blob/master/README.md) diff --git a/README.md b/README.md index 181198099..287e9fa70 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,10 @@ +This repository contains the base source files and tools for converting +PHP's documentation, written in DocBook XML, into various presentation +formats like HTML and RTF. -# Read this first +Documentation for the tools used for building the PHP documentation and +how to contribute to the documentation and translations can be found in +[the `docs` directory](docs/README.md). -This directory contains source files and a setup for converting -PHP's XML documentation into presentation formats like HTML and -RTF. You should not have to bother with this unless you are -writing documentation yourself, or if you simply are curious -about how the XML stuff works. - -If you just want to read the documentation, look at: +If you just want to read the documentation for PHP, look at: https://www.php.net/docs.php - -# How to write phpdoc files - -If you are interested in information about how to -set up the tools needed, how to work with Git and -DocBook on Linux or Windows, or what conventions you -should follow when writing phpdoc files, please refer -to the PHP Documentation HOWTO. - -The PHP Documentation uses the [DocBook 5.2](https://tdg.docbook.org/tdg/5.2/) XML schema. \ -However, there is one small change between the official Docbook 5.2 schema and the schema used by the PHP documentation: -the `` tag allows "One or more Oriented Object Programming inlines", -like the [DocBook 5.1](https://tdg.docbook.org/tdg/5.1/classsynopsis) schema does, -instead of "One Oriented Object Programming inlines". - -You can read the HOWTO online at: http://doc.php.net/tutorial/ - -If you are already working with the phpdoc module, -then you can find its XML source in the howto directory -of the module, and build it yourself with: - -```bash -phd -d .manual.xml -``` - -However, PhD is a separate project which can be read about here: -https://wiki.php.net/doc/phd - -## Quick reference - -### Source checkout - -For a more general git-workflow see [the Wiki](https://wiki.php.net/vcs/gitworkflow#reviewing_and_closing_pull_requests). -Make sure to upload your SSH public key to your account at main.php.net - -Check out the sources: - -```bash -mkdir phpdoc -cd phpdoc -git clone git@github.com:php/doc-en.git en -git clone git@github.com:php/doc-your-language-of-choice.git your-language-of-choice -git clone git@github.com:php/doc-base.git -``` - -Change `your-language-of-choice` if you would like to check out a different language. - -The `en` folder contains the English DocBook source files, and `doc-base` contains tools -and resources used in all languages. - -### Edits - -* Make the change. Use spaces not tabs. Be sure to carefully watch your whitespace! -* cd into the desired clone directory, e.g. - ```bash - cd en - ``` -* Look at your unified diff, make sure it looks right and that whitespace changes aren't mixed in: - ```bash - git diff path/to/file.xml - ``` -* Make sure no errors are present, so at the command line in your phpdoc source directory run: - ```bash - php ../doc-base/configure.php - ``` -* If you are translating, remember to add the full Git commit hash of the English file that you are translating - from, to the file's `EN-Revision` comment. -* Commit your changes - ```bash - git commit path/to/file.xml - ``` - -Read the HOWTO for more information. After reading the HOWTO, -email the phpdoc mailing list (phpdoc@lists.php.net) with questions -and concerns. - -### New functions - -* Copy an existing XML file or use a skeleton from the HOWTO. - Rename and place it into the appropriate directory. -* Edit. Be sure no leftover text exists. No tabs either. -* If you are translating, remember to add the full Git commit hash of the English - file that you are translating from, to the file's `EN-Revision` comment. -* cd into the desired clone directory, e.g. - ```bash - cd en - ``` -* Now test locally before commit by first running - ```bash - php ../doc-base/configure.php - ``` -* Add the file to your staging area - ```bash - git add path/to/yourfile.xml - ``` -* Commit the file and push it to the git-server - ```bash - git commit path/to/yourfile.xml - git push remote your-branch - ``` -* Open a pull request to the main repository via GitHub - -### Some popular tags and entities - - filenames - constants - variables - a function's parameter/argument - functions, this links to function pages or bolds if - already on the function's page. it also adds (). - - teletype/mono-space font - italics - see HOWTO, includes many other tags. - internal manual links - variables - - external links via global.ent - mmm cookies - - types, this links to the given types manual - page: object -> php.net/types.object - - &return.success; see: language-snippets.ent - &true; TRUE - &false; FALSE - &php.ini; php.ini - -Be sure to check out [global.ent](entities/global.ent) and -language-snippets.ent (located within each language's repo) for -more information for entities and URLs. - -# Quality Assurance Tools (QA Tools) - -There are various scripts available to ensure the quality of the documentation -and find issues with it, they are located in the `scripts/qa/` directory. - -There might be some more just in `scripts/` but they need to be checked if they -are still relevant and/or given some love. - -# Translation Tools - -There are also various scripts to ensure the quality and synchrony of -documentation translations, located in the `scripts/translation/` directory. - diff --git a/RFC/coding_standards b/RFC/coding_standards deleted file mode 100644 index 3745e753a..000000000 --- a/RFC/coding_standards +++ /dev/null @@ -1,257 +0,0 @@ -GENERAL: - -References: http://pear.php.net/manual/en/standards.php - http://www.php.net/manual/howto/ - -Examples need to be clear and simple, but should show the possibilities and -usage of the functions used. Only use OOP features where you would like to -present them, use simple functions in other areas. - -Example guidelines: - -0. Requirements - - - Work with register_globals on or off - - When appropriate, use superglobals - - Never generate PHP errors (E_ALL|E_STRICT friendly) - - Be short and generic - - Follow the PEAR coding standards - -1. Program listing roles () - - PHP examples should always have programlisting role="php" Only PHP - examples should have this role. Possible roles are: - - - c (C code) - - html (100% XHTML) - - php (Some PHP) - - shell (commandline, bash, etc) - - sql (SQL statements) - - apache-conf (Apache) - -2. Titles - - When appropriate, it's encouraged to include the function name in - the title, for example: - - A <function>strlen</function> example - -3. Code placement - - The contents start at column/row 0 in the example. For example, this - means your example's content will be flush against the as this increases the readability of the - examples. For example, you literally write < instead of < inside - of CDATA. Nothing in CDATA is parsed, it's taken literally. So, you - cannot use links, dev-comments, , etc. - -6. Deprecated code - - Do not use aliases or deprecated syntax. - -7. Use of newer PHP features - - If an example uses features, such as arguments specific to a newer - version of PHP, add a comment that mentions this. For example: - - // Second argument was added in PHP 4.1.0 - foo('bar', 'baz'); - - If appropriate, show examples that work in older versions of PHP but - do not use reserved function names. For example, a PHP 4.2.3 version - of file_get_contents() should not be named file_get_contents(). - -8. Use of booleans in examples - - Do not use entities such as &true; in examples but instead write them - out as TRUE, FALSE, and/or NULL. (See point#5) - -9. Spacing - - Never use tabs, only use spaces. Intention levels are four spaces - and do not intent the first level of code. For example: - - Good: - ------------------------- - - - Bad: - ------------------------- - -10. IDs - - It is a good idea to add xml:id to the examples. IDs generate anchors and - make it possible to list them in an Example Listing Appendix in the future. - - -ERROR HANDLING - -This section isn't yet complete but there are three main ways to -implement error handling in the PHP manual: - - a) Use of the 'or' operator. - - This is okay for development code but not ideal for production as use - of 'or' is rather limiting. An example use: - - foobar($lname) or die(...); - - b) A boolean check, along with {braces} - - This allows additional expressions inside the {braces} but requires - more code. This is the preferred method. An example use: - - if (!foobar($lname)) { - ... - exit; - } - - d) trigger_error() - - There is debate on whether to use trigger_error() in the examples fo for - now, do not use it (at least until the error handling docs are updated). - -ABOUT VARIABLES/CONSTANTS/STRINGS: - -1. Don't use variables which are not set in examples. - -2. Constants should always be all-uppercase. - -3. Use single quotes ' when appropriate. - -4. For output use echo, instead of print. - -5. Lowercase html-tags. - -6. Variables in strings: - - Strings in strings - - This is of course debatable and subject to personal preference. The - two main methods are inline or concatenation: - - echo "bar is $bar"; - echo "bar is {$bar}"; - vs - echo 'bar is ' . $bar; - - All of the above methods are acceptable. - - Arrays in strings - - As constants aren't looked for in strings, the following is fine - but may confuse newbies so it's not to be used in examples: - - echo "an $array[key] key"; - - Instead, consider these: - - echo "an {$array['key']} key"; - echo 'an ' . $array['key'] . ' key'; - - -HOWTO WRITE... - -A: CONTROL STRUCTURES - -See PEAR coding standards - -B: FUNCTIONS: - -1. FUNCTION NAMING: - -Procedural function names should be lowercase. If multiple words are -needed in the function name, use a _. Example: foo_function(); - -OOP function names should follow the PEAR Coding Standards which -would be fooFunction(). - -2. FUNCTION CALLS -3. FUNCTION DEFINITIONS - -See PEAR coding standards - -C: COMMENTS -D: EXAMPLE URLS/EMAIL - -See PEAR coding standards - -E: EXAMPLE PRINTOUTS - -For very short example printouts, use C++ style comment (//) on the -line where the output occurs, or in the description above the line: - -echo $var; // 32 - -For longer example printouts, there are a couple methods which are -acceptable. Medium sized output may be inline with the example -itself through use of /* comments */, for example: - - 'bread' - [1] => 'peanut butter' - [2] => 'jam' -) -*/ -?> - -For longer example printouts, use the container in conjunction -with - - - &reftitle.examples; - - A <function>foo</function> example - - -]]> - - &example.outputs; - - 'a'; - [1] => 'b'; - [2] => 'c'; - ... -) -]]> - - - - - -COMPLETE EXAMPLE SKELETON - -See the HOWTO diff --git a/RFC/pdf_problems b/RFC/pdf_problems deleted file mode 100644 index 03c8c4793..000000000 --- a/RFC/pdf_problems +++ /dev/null @@ -1,43 +0,0 @@ -Here are the problems with building a PDF version of the manual: - -1. The currently "used" jade / jadetex / dvipdfm run takes much time, as - jadetex needs to be run three times[!] to find all crossreferences - correctly. The process works this way: - - - jade is run on the XML source with the DSSSL print stylesheet to - create a tex version - - jadetex is run 3 times on the tex source to create a dvi - - dvipdfm is run to convert the dvi to pdf - -2. The limits set while setting up jadetex on the build machine are - not sufficient, the current manual size exceeds them. [Hartmut's - observation] - -What would be the goal? - - We have a plan to convert all jade / DSSSL based conversions to XSLT. - The current extended CHM is already created with XSLT and xsltproc. - Xsltproc seems to be the fastest conversion tool. It is writen in C, - so there is no need to setup a JVM to use it, and is also part of - cygwin [for windows users]. Xsltproc is already slightly integrated - to the build system (it is checked for, and html_xsl and chm_xsl - make targets use it). - -How would that work? - - - run xsltproc (or some other xslt processor) to convert XML -> FO with XSLT - - run FOP to convert FO -> PDF - - Of course for one "make pdf" command. - -Cons - - Last time Hartmut checked it, FOP was unable to do all the needed - conversions to generate the correct PDF file out of the FO source. - -Pros - - - it would be significantly faster - - we would have a PDF version finally - - XSLT is easier to modify then the more cryptic DSSSL, there are more - tools and more manuals for it \ No newline at end of file diff --git a/RFC/schema/docbook.xsd b/RFC/schema/docbook.xsd deleted file mode 100644 index c33dcc21e..000000000 --- a/RFC/schema/docbook.xsd +++ /dev/null @@ -1,17427 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/RFC/schema/phd.dtd b/RFC/schema/phd.dtd deleted file mode 100644 index 2ba87b27b..000000000 --- a/RFC/schema/phd.dtd +++ /dev/null @@ -1,30 +0,0 @@ - - - - - - - - - - - - - - - - - - - diff --git a/RFC/schema/phd.xsd b/RFC/schema/phd.xsd deleted file mode 100644 index 897d24b90..000000000 --- a/RFC/schema/phd.xsd +++ /dev/null @@ -1,90 +0,0 @@ - - - - - - -]> - - - - - PhD normative schema version 1.0. - Copyright(c) 2007 The Author(s). All Rights Reserved. - The Author(s) are described in a LICENSE file which should have accompanied - this document; if you did not receive this file, it can be downloaded from - the world-wide-web at: - <http://phd.php.net/LICENSE> - - $Id$ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/RFC/schema/xlink.xsd b/RFC/schema/xlink.xsd deleted file mode 100644 index ff9a7c1de..000000000 --- a/RFC/schema/xlink.xsd +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/RFC/schema/xml.xsd b/RFC/schema/xml.xsd deleted file mode 100644 index c6e9c4621..000000000 --- a/RFC/schema/xml.xsd +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - - - - - - - - diff --git a/RFC/test.xml b/RFC/test.xml deleted file mode 100644 index 6f9d4b45b..000000000 --- a/RFC/test.xml +++ /dev/null @@ -1,49 +0,0 @@ - - - - - An XML file that is meant to be ignored -
- Testing - - - test commit from local version of the editor : new structure for modified files. - - Ignore me, unless you're test committing. - Creating test commit as "anonymous" but with an email address. - Test - -
- - - diff --git a/TODO b/TODO deleted file mode 100644 index 37c6dea0e..000000000 --- a/TODO +++ /dev/null @@ -1,42 +0,0 @@ -TODO for the PHP documentation project. - -Last update date: $LastChangedDate$ - -Add things that should be updated/added in the documentation here. For -big (i.e. time-consuming) items, add your name to it when you start -working on it, to prevent double-work. - -BIG JOBS: - - build PDF's - - see: RFC/pdf_problems - - Move the "developers manual" (internals) to http://dev.php.net - - see: RFC/manual_splitting - - integrate the meeting findings from the protocol - - see: RFC/protocol_20020310 - - document every undocumented function. - - add an example to most every function - -BUILD SYSTEM: - - get back lost indexes, but add them as appendices - (index of tables, index of examples, index of config options) - - add legacy.ent - - see: http://marc.theaimsgroup.com/?l=phpdoc&m=103893809326045 - - generate a list of all php.ini configure options - - generate a list of all install configure options - - generate a list of all requirements from all resources.xml - -GENERAL: - - Go through the FIXMEs comments - - Document php://stdout etc feature for file functions. - (superseded by need of general description of the new streams features?) - - Add ¬e.not-threadsafe; to each extension/function - that is not thread safe - - go through and make sure every function that takes on a parameter - by reference has an example that clearly demonstrates that it's - not a reference passed at call time. - - Add a pointers section, perhaps in types.array - - Tool: check all 'see also' links and ensure they are valid. For - example, make sure a function exists. - -BUGS - - Open: http://bit.ly/phpdocbugs diff --git a/contacts.txt b/contacts.txt deleted file mode 100644 index 110c24a77..000000000 --- a/contacts.txt +++ /dev/null @@ -1,38 +0,0 @@ -A list of SVN account contacts who are likely able -to answer questions about these translations. - -Languages with existing SVN modules: ------------------------------------- - -ar visualmind -bg kouber -ca uri -cs luk -da kalle -de cmb -el -en salathe -es yago -fi sniper -fr dams,didou -he momo,doron -hk -hu chappy -id salman -it cortesi -ja takagi -kr progcom -lt shivas (dead, no translation) -nl derick (dead, no translation) -no knut -pl sobak -pt nlopess (dead, no translation) -pt_BR ae -ro simionea -ru tronic -sk joseph -sl dejan (dead, no translation) -sv jome -tr nilgun -tw gregory -zh dallas diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..b8e23447b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,36 @@ +# PHP Manual Contribution Guide + +## Introduction + +PHP is well-known for having excellent documentation. That documentation +is created by volunteers who collectively make changes every day, and +actively translated into many languages. This guide is designed for +people who work on the official PHP documentation. + +The manual is built from the documentation using a tool called +[PhD](http://doc.php.net/phd.php). The [local setup](local-setup.md) +chapter explains how to set up a local development environment. + +The manual is written to the [DocBook 5.2](https://tdg.docbook.org/tdg/5.2/) +XML schema, with one change to allow the `` tag to support +more than one ``, ``, or `` as the +[DocBook 5.1](https://tdg.docbook.org/tdg/5.1/classsynopsis) schema does. + +## Glossary + +This guide uses some terminology that you have to know. Don't worry, it's easy: + +- **author** - person who contributes to the original English manual +- **translator** - person who translates the English manual into another + language +- **{LANG}** - replace it with your two-letter country code, (e.g. when + referring to a mailinglist, `doc-{LANG}@lists.php.net`). Note: + Brazilian Portuguese differs from the rest and it's called *pt_br* + for the Git repo and *pt-br* for the mailing list suffix. + +## Feedback + +You can report problems or make contributions to this guide by using the +"Edit this page" or "Report a problem" links in the sidebar of each page +of [the online version of this documentation](https://doc.php.net/guide/), +or through [the GitHub repository](https://www.github.com/php/doc-base/). diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 000000000..a1c5dd0bc --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,75 @@ +# Contributing to the PHP Documentation + +You can easily contribute to the PHP documentation +by either [reporting a bug](#report-a-bug) +or by fixing one by [submitting a pull request](#submit-a-pull-request). +As all the repositories are hosted on GitHub, +you will need a GitHub account to do either of these. + +## Report a Bug + +If you have found a bug on any of the PHP documentation pages, +you can file a bug report by doing the following: + +- click the "Report a Bug" link in the "Improve This Page" section + on the bottom of the page +- log into GitHub +- add a short description of the bug in the title textbox +- add all necessary details to the description textarea +- click the "Submit new issue" button to file your bug report + +## Submit a Pull Request + +There are two ways to make changes to the documentation: +- make [minor changes](#minor-changes) by editing files on GitHub +- make [more complex changes](#more-complex-changes--building-the-php-documentation) + and validate/build the documentation locally on your computer + +## Minor changes + +To make trivial changes (typos, shorter wording changes or adding/removing short segments) +all one needs is a web-browser and a GitHub account and doing the following: + +- click the "Submit a Pull Request" link in the "Improve This Page" section + on the bottom of the documentation page +- log into GitHub +- fork the repository (if you have not forked it already) +- make changes +- click the "Commit changes" button +- add a commit message (short description of the change) into the "Commit message" textbox +- write a longer description in the "Extended description" textarea, if needed +- click the "Propose changes" button +- review your changes and click "Create pull request" button + +The repository will run a few basic checks on the changes +(e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.) +and your PR is ready to be discussed with and merged by the maintainers. + +## More Complex Changes / Building the PHP documentation + +To build and view the documentation after making more extensive changes +(e.g. adding entire sections or files), you will need to +[set up a local build environment](local-setup.md) +in addition to the language repository you want to +[make the changes](#make-changes-to-the-documentation) to. +If the changes validate and look good, you can +[open a PR](#commit-changes-and-open-a-pr). + +If you'd like to know more about what each repository is +and/or how PHP's documentation is built please refer to +the [overview](overview.md). + +### Make changes to the documentation + +[Make your changes](editing.md) keeping in mind the [style guidelines](style.md). + +### Commit changes and open a PR + +- commit your changes +- push to your fork +- open a PR in the appropriate language repository + +Once you open a PR, the documentation repository will run a few basic +checks on the changes (e.g. whether the XML markup is valid, whether +trailing whitespaces are stripped, etc.) and your PR is ready to be +discussed with and merged by the maintainers. diff --git a/docs/cs-for-examples.md b/docs/cs-for-examples.md new file mode 100644 index 000000000..ec370d091 --- /dev/null +++ b/docs/cs-for-examples.md @@ -0,0 +1,295 @@ +# Coding standard for examples + +Examples need to be clear and simple, but should show the possibilities and +usage of the functions used. Only use OOP features where you would like to +present them, use simple functions in other areas. + +Examples should generally conform to the [PEAR coding standards][pear-cs]. + +## Requirements + +- When appropriate, use superglobals +- Never generate PHP errors (`E_ALL|E_STRICT` friendly) +- Be short and generic +- Follow the PEAR coding standards + +## Program listing roles (``) + +PHP examples should always be in ``. +Only PHP examples should have this role. +Other possible roles are: + + - c (C code) + - html (100% XHTML) + - php (Some PHP) + - shell (commandline, bash, etc) + - sql (SQL statements) + - apache-conf (Apache) + +## Titles + +When appropriate, it's encouraged to include the function name in +the title, for example: + +```xml +A <function>strlen</function> example +``` + +## Code placement + +The contents start at column/row 0 in the example. For example, this +means your example's content will be flush against the `` as this increases the readability of +the examples. For example, you literally write `<` instead of `<` +inside of CDATA. Nothing in CDATA is parsed, it's taken literally. +So, you cannot use links, dev-comments, ``, etc. + +## Deprecated code + +Do not use aliases or deprecated syntax. + +## Use of newer PHP features + +If an example uses features specific to a newer version of PHP, such +as new arguments that has been added, this should be made clear in the +title of the example. + +```php + + <function>foo</function> with second argument added as of PHP 8.1.0<title> + <programlisting role="php"> +<![CDATA[ +<?php +foo('bar', 'baz'); +?> +]]> + </programlisting> +</example> +``` + +If appropriate, show examples that work in older versions of PHP but +do not use reserved function names. For example, a PHP 4.2.3 version +of `file_get_contents()` should not be named `file_get_contents()`. + +## Use of booleans in examples + +Do not use entities such as `&true;` in examples but instead write them +out as `true`, `false`, and/or `null`. + +## Spacing + +Never use tabs, only use spaces. Indentation levels are four spaces +and do not indent the first level of code. For example: + +### Good: +```php +<?php +$str = 'Hello World'; +function foo($str) +{ + return $str; +} +?> +``` + +### Bad: + +```php +<?php + $str = 'Hello World'; + function foo($str) + { + return $str; + } +?> +``` + +## IDs + +It is a good idea to add xml:id to the examples. IDs generate anchors and +make it possible to list them in an Example Listing Appendix in the future. + + +## Error handling: + +This section isn't yet complete but there are three main ways to +implement error handling in the PHP manual: + +a) Use of the `or` operator. + +This is okay for development code but not ideal for production as use +of `or` is rather limiting. An example use: + +```php +foobar($lname) or die(...); +``` + +b) A boolean check, along with braces + +This allows additional expressions inside the braces but requires +more code. This is the preferred method. An example use: + +```php + if (!foobar($lname)) { + ... + exit; + } +``` + +c) `trigger_error()` + +There is debate on whether to use `trigger_error()` in the examples so for +now, do not use it (at least until the error handling docs are updated). + +## About Variables/Constants/Strings + +1. Don't use variables which are not set in examples. + +2. Constants should always be all-uppercase. + +3. Use single quotes ' when appropriate. + +4. For output use `echo`, instead of `print`. Don't use unnecessary + string concatenation (`.`) with `echo`, use `,` instead. + +5. Lowercase HTML tags. + +6. Variables in strings: + +* Strings in strings + +It is acceptable to use either string interpolation or concatenation +when composing strings, but `,` should be used to separate multiple +expressions for `echo` is preferred to string concatenation. + +```php +$output = "bar is $bar"; +echo "bar is $bar"; +$output = "bar is {$bar}"; +echo "bar is {$bar}"; +``` +vs +```php +$output = 'bar is ' . $bar; +echo 'bar is ', $bar; +``` + +* Arrays in strings + +As constants aren't looked for in strings, the following is fine but +may confuse newbies so it's not to be used in examples: + +```php +$variable = "an $array[key] key"; +echo "an $array[key] key"; +``` + +Instead, consider these: + +```php +$variable = "an {$array['key']} key"; +echo "an {$array['key']} key"; +echo 'an ', $array['key'], ' key'; +``` + +## How to write... + +### Control Structures + +See PEAR coding standards + +### Functions + +#### Function naming + +Procedural function names should be lowercase. If multiple words are +needed in the function name, use a `_` (also known as snake\_case). +Example: `foo_function();` + +OOP method names should follow the standard coding style which uses +camelCase, such as `fooFunction()`. + +#### Function calls +#### Function definitions + +See PEAR coding standards + +### Comments +### Example URLs/Emails + +See PEAR coding standards + +### Example output + +For very short example printouts, use C++ style comment (`//`) on the +line where the output occurs, or in the description above the line: + +```php +echo $var; // 32 +``` + +For longer example printouts, there are, a couple methods which are +acceptable. Medium sized output may be inline with the example +itself through use of `/* comments */`, for example: + +```php +<?php +$arr = foo(); +var_dump($arr); + +/* Outputs: + +array(3) { + [0]=> + string(5) "bread" + [1]=> + string(13) "peanut butter" + [2]=> + string(3) "jam" +} +*/ +?> +``` + +For longer example printouts, use the `<screen>` container in conjunction +with `<![CDATA[...]]>` + +```xml + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>A <function>foo</function> example + + +]]> + + &example.outputs; + + + string(1) "a" + [1]=> + string(1) "b" + [2]=> + string(1) "c" +} +]]> + + + +``` + +[pear-cs]: http://pear.php.net/manual/en/standards.php diff --git a/docs/editing.md b/docs/editing.md new file mode 100644 index 000000000..21d675584 --- /dev/null +++ b/docs/editing.md @@ -0,0 +1,65 @@ +# Editing manual sources + +Before making any changes to the manual - either the English version or a +translation, make sure you have read the [style guidelines](style.md)! + +## Editing existing documentation +Simply open the files and edit them. + +## Adding new documentation +When adding new functions or methods, there are a few options: + +### Option A: Generating stub using `gen_stub.php` +This is the new preferred way to generate files for new extensions, classes, functions +or methods using [`get_stub.php`][gen_stub]. The script is found in the [php-src][php-src] +repository and uses the stub files to generate documentation (DocBook) files. + +### Option B: Generating files using docgen +This is the old 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 C: Copy skeleton files +This involves copying the skeleton files into the correct location: +``` +cp doc-base/skeletons/method.xml classname/methodname.xml #for new methods +cp doc-base/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.md) when copying those files. + +## Translating documentation +The translation process is described in the [translating chapter](translating.md). + +## 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 access to the repository, you can commit your modified files. +Otherwise, create a Pull Request to have your changes reviewed by the team. + +## Viewing changes online +The documentation used on the PHP.net website is rebuilt every few hours from +the latest source pushed to the documentation trees. + +Read more details in [the appendix on public builds](public-builds.md). + +[docgen]: https://github.com/php/doc-base/tree/master/scripts/docgen +[doc-base]: https://github.com/php/doc-base/ +[gen_stub]: https://github.com/php/php-src/tree/master/build/gen_stub.php +[php-src]: https://github.com/php/php-src/ +[configure.php]: https://github.com/php/doc-base/blob/master/configure.php diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..57475027f --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,81 @@ +# Frequently Asked Questions + +## I'm about to document a new PHP extension. How should I start? +Change your working directory to `phpdoc/doc-base/scripts/docgen/` and execute: +```sh +php docgen.php -e simplexml -o outdir +``` + +It creates the skeletons that you edit, and then commit. + +Help is available with following command: `php docgen.php -h`. + +## I created skeletons that contain a bunch of default text, should I commit it? +No! Edit the files, to check the generated content and add more information +before committing. Thinking that it is okay to commit the skeleton files because +you will soon come along and flesh them out might seem like a good idea. However, +temporary often becomes permanent. + +## Is there an online editor? +No, but [simple changes can be submitted via GitHub](contributing#minor-changes). + +## How do I add a link to a method? +Use `Class::method`. Note that the case does not matter when adding a link. + +## If a refentry should not emit versioning information, what should I do? +Add the `role="noversion"` to its ``. Example: +```xml + +``` + +## How do I add an external link to the documentation? +All external links are added to `doc-base/entities/global.ent`. Markup looks as follows: +```xml + +``` +Then you can use this syntax in the documentation: +```xml +Check out Google +``` +Be sure the file understands the `xlink` namespace, by using `xmlns:xlink="http://www.w3.org/1999/xlink"` in the document element. + +## When adding a note, should I add a title? +Typically titles are useful for notes, but it's not required. +```xml + + Foo + Note contents are here. + +``` + +## A feature became available in PHP X.Y.Z, how do I document that? +Version information for functions is stored inside `versions.xml` within +each extension (e.g. `phpdoc/en/extname/versions.xml`). Changes to functions, +like added parameters, are documented within the changelog section for each page. + +## A parameter is optional, how is it documented? +Like normal, except `methodparam` receives the `choice="opt"` attribute, and +the `` tag is used to signify the default value. +```xml + + bool + httponly + false + +``` + +## I see example.outputs and example.outputs.similar entities, what's the difference? +The `&example.outputs.similar;` entity is used when the output may differ between executions or machines. +The `&example.outputs;` entity output will always, under all conditions, be the same. + +## I need to add a piece of text to three or more pages, how? +Add the snippet to `en/language-snippets.ent` as an entity and link to the entity within the desired pages. +This is done so translators can update one version of this text. + +## How do I find missing documentation? +Missing functions (no associated XML files) can be found like so (assuming a doc checkout, and PhD is installed): +```sh +php doc-base/configure.php +phd --docbook doc-base/.manual.xml --package PHP --format php +php doc-base/scripts/check-missing-docs.php -d output/index.sqlite +``` diff --git a/docs/joining.md b/docs/joining.md new file mode 100644 index 000000000..a552ff39f --- /dev/null +++ b/docs/joining.md @@ -0,0 +1,59 @@ +# Joining the team + +Joining the PHP Documentation team is a simple process, but a process nonetheless. +You don't have to the join the team to [contribute](contributing.md), +but joining the team can be a way to get more involved in the process +and help out with larger projects. + +## Write to a mailing list +Because official communication is done there, you should write to the proper list. +Say "Hi" and what you're interested in doing. You may feel more comfortable lurking +for a while, or reading the archives, but ultimately let the list know who you are. + +### For authors +You should send your message to the `phpdoc@lists.php.net` mailing list. You +will need to subscribe to the list in order to send email to it. You can find +[archives of the list on news-web.php.net](https://news-web.php.net/php.doc), +and there is also a form to subscribe to the list there. + +You can subscribe the regular version of the list (you get every +message as it is sent), the digest version (you'll get a daily-or-so +mail containing all of the new messages to the list), or the "no mail" +version which allows you to send a message but doesn't send you any emails +(useful if you just read through the web archive or an NNTP client). + +### For translators +You should send your message to the appropriate `doc-{LANG}@lists.php.net` mailing list. + +## Informal discussion +The mailing lists above are the primary communication forum. In particular, +decisions and plans should be made on the list so they are recorded in the +archives. + +However for more realtime and/or informal chat, some doc authors hang out in +"Room 11" on Stackoverflow Chat: https://chat.stackoverflow.com/rooms/11/php + +Some authors hang out in the `#php-doc` channel on IRC on the +https://Libera.Chat network, which is also bridged to the Discord server run +by the PHP Community Foundation, available at https://phpc.chat. + +## Create a doc patch or three +This step is required to show us that you are a real human, you want to do +some work and in general know how to do this. + +The simplest way to get started is by using GitHub, to create and send Pull Requests +to [php/doc-en][doc-en] or php/doc-{LANG} for translations. + +Your Pull Requests will be then reviewed and accepted by someone with Git commit access. + +## Obtaining Git commit access +If you plan to contribute to the manual regularly and want to help process +contributions from others, you might want to request to be added to the +documentation team (or a translation team) on GitHub, which you can do on the +email lists. + +To be clear: you don't need Git commit access to start contributing to the +documentation! Anyone with a GitHub account (which is free) can submit Pull +Requests to the documentation repositories. + +[doc-en]: https://github.com/php/doc-en diff --git a/docs/local-setup.md b/docs/local-setup.md new file mode 100644 index 000000000..a96cba607 --- /dev/null +++ b/docs/local-setup.md @@ -0,0 +1,105 @@ +# Setting up a local development environment + +This guide assumes that you are comfortable working with on the +command line with tools like Git. + +There are instructions for building [with Docker](#with-docker) or +[without Docker](#without-docker). Building with Docker means that +not all of the related repositories need local clones, and that you +will be building with a version of PHP that is known to work. + +When working with multiple translations, or working on changes that may +also require changing files in the `doc-base` or `phd` repositories, the +suggested way to organize the local enviroment is to clone repositories +into a single `phpdoc` directory, and for individual languages to be cloned +into directories named `{LANG}` instead of `doc-{LANG}` as they are named +on GitHub. + + +## Building with make and Docker + +- Install Docker (https://docs.docker.com/get-docker/) +- Clone the `doc-en` Git repository +- Rebuild the documentation using `make` +- Open output/php-chunked-xhtml/ in your browser. + +```sh +$ mkdir phpdoc +$ cd phpdoc +$ git clone https://github.com/php/doc-en.git en +$ cd en +$ make +$ open output/php-chunked-xhtml/index.html +``` + +If the `doc-base` or `phd` repositories are available in directories +adjacent the clone of the `doc-en` repository, those will be used for +building, otherwise the latest revision of those repositories from GitHub +will be built into the Docker image used. + +To force the Docker image used for building to itself be rebuilt, run +`make -B build`, otherwise the `Makefile` will only build it if does not +already exist. + +The web version of the documentation with `make php` and the output will +be placed in `output/php-web`. (See the [additional local web setup +instructions](local-web-setup.md) for details on how to view those.) + + +## Building without make or Docker + +## Check out the PHP documentation using Git + +Note that `doc-en` is cloned into the `en` directory below. + +``` +$ mkdir phpdoc +$ cd phpdoc +$ git clone https://github.com/php/phd.git +$ git clone https://github.com/php/doc-base.git +$ git clone https://github.com/php/doc-en.git en +``` + +## Validate and build `.manual.xml` + +``` +$ php doc-base/configure.php +``` + +Running `configure.php` will check and validate the XML according to the +Docbook specification. It will output either error messages explaining +any problems, or an ASCII cat. + +This creates the file `doc-base/.manual.xml` which can then be used +to generate other formats of the documentation. + +If you are building a translation, you'll also need to specify the +language at this step: + +```sh +$ git clone https://github.com/php/doc-fr.git fr +$ php doc-base/configure.php --with-lang=fr +``` + +When building a language, you still need to clone both the `doc-en` repository +(again, as `en`) so it can be used as the fallback for files that are not yet +translated. + +## Build other formats of the documentation + +`phd` can turn the `doc-base/.manual.xml` generated by `configure.php` +into several different formats, including a single HTML file, a +multiple-file ("chunked") HTML version, and a special version of the +HTML used by the PHP.net website. + +```sh +$ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml +$ open output/php-chunked-xhtml/index.html +``` + +To build the version for the website (with a [local web setup](local-web-setup.md)): + +```sh +$ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format php +$ open https://localhost:8080/manual/en/ +``` diff --git a/docs/local-web-setup.md b/docs/local-web-setup.md new file mode 100644 index 000000000..cf0b021b4 --- /dev/null +++ b/docs/local-web-setup.md @@ -0,0 +1,32 @@ +# Setting up a local web development enviroment + +## Clone the php.net sources +``` +$ git clone https://github.com/php/web-php.git +``` + +## Symlink (or move) the generated PHP documentation to your local php.net sources +``` +$ cd web-php/manual +$ rm -rf en +$ ln -s ../../output/php-web en +``` + +Symlinking can also be done on Windows. Just make sure you run `cmd` as an *Administrator*. + +``` +$ cd \your\path\to\web-php\manual\ +$ rmdir /S en +$ mklink /D en \your\path\to\output\web-php +``` + +## Run a webserver +We are going to use PHP's built-in web server. Please open another terminal instance for this task. + +``` +$ cd phpdoc/web-php +$ php -S localhost:8080 .router.php +``` + +## View the new site +Open [http://localhost:8080/manual/en/](http://localhost:8080/manual/en/) in your browser. diff --git a/OVERVIEW.md b/docs/overview.md similarity index 73% rename from OVERVIEW.md rename to docs/overview.md index dd6e24d7b..8d00fff60 100644 --- a/OVERVIEW.md +++ b/docs/overview.md @@ -1,4 +1,4 @@ -# The PHP Documentation +# Overview of the build system The PHP documentation is built from XML files and render into PHP files that are available on the [php.net/manual](https://php.net/manual/en) pages. @@ -21,9 +21,8 @@ These repositories contain PHP's documentation in their respective languages and these are where changes to the content/structure of the [php.net's documentation pages](https://www.php.net/docs.php) are made. -Please refer to [doc-base's](https://github.com/php/doc-base) -[contribution guidlines](https://github.com/php/doc-base/blob/master/CONTRIBUTING_DOCS.md) -on how to contribute to the documentation. +Please refer to the [contribution guidlines](contributing.md) on how to +contribute to the documentation. ## doc-base @@ -39,10 +38,6 @@ and the `configure.php` script which processes the documentation: - subtitutes entities - validates the document based on its DTD -Please refer to [doc-base's](https://github.com/php/doc-base) -[contribution guidlines](https://github.com/php/doc-base/blob/master/CONTRIBUTING_DOCS.md) -on further details on how to use doc-base. - ## PhD [PhD](https://github.com/php/phd) (PHP DocBook) renders the combined XML file, @@ -67,24 +62,22 @@ Other than the above PhD also does the following: - generates and saves the TOC (table of contents) files (the TOC/navbar on the right side of the documentation pages) -Please refer to [doc-base's](https://github.com/php/doc-base) -[contribution guidlines](https://github.com/php/doc-base/blob/master/CONTRIBUTING_DOCS.md) -on further details on how to use PhD. - ## web-php [web-php](https://github.com/php/web-php) is the repository that PHP's web servers actually run (ie. almost everything accesible on [php.net](https://php.net)). -This repository includes the functions that generate the header (top navigation and search bar) -and footer (copyright, privacy policy, etc.) for most php.net pages -and it also includes the functions that generate the additional header (breadcrumbs, language dropdown, etc.) +This repository includes the functions that generate the header (top +navigation and search bar) and footer (copyright, privacy policy, +etc.) for most php.net pages and it also includes the functions that +generate the additional header (breadcrumbs, language dropdown, etc.) and footer (contribution and user notes sections) of documentation pages. -It uses the css, image, TOC and search index/description files copied/generated by PhD -to serve up images/css files, generate the right side TOC/navbar on the documentation pages -and make the search bar on [php.net](https://php.net) work. +It uses the css, image, TOC and search index/description files +copied/generated by PhD to serve up images/css files, generate the right +side TOC/navbar on the documentation pages and make the search bar on +[php.net](https://php.net) work. -Please refer to [doc-base's](https://github.com/php/doc-base) -[contribution guidlines](https://github.com/php/doc-base/blob/master/CONTRIBUTING_DOCS.md) -on further details on how to use web-php. +The [local web development environment](local-web-setup.md) chapter +explains how to run the `php-web` repository locally so you can build +the documentation and review it as it will appear online. diff --git a/docs/public-builds.md b/docs/public-builds.md new file mode 100644 index 000000000..eeeaec962 --- /dev/null +++ b/docs/public-builds.md @@ -0,0 +1,18 @@ +# How the manual is built for the website + +The manual and all of its translations is automatically rebuilt and +made available at PHP.net through a regular process handled by the +systems team. + +Currently, this happens every few hours. + +If there appear to be problems with the regular building of the manual or +any translation, contact the [PHP Systems team](mailto:systems@php.net) +for help. (The process is automated and monitored, so problems are +generally dealt with promptly.) + +## CHM builds + +The CHM versions of the manual are currently built by [Yoshinari +Takaoka](https://github.com/mumumu) on an irregular schedule, and are +automatically made available for distribution when they are rebuilt. diff --git a/docs/structure.md b/docs/structure.md new file mode 100644 index 000000000..dcc63f6f1 --- /dev/null +++ b/docs/structure.md @@ -0,0 +1,44 @@ +# Documentation structure + +The PHP Manual sources are stored in Git repositories. + +To checkout the PHP Manual sources, follow the steps in [Setting up a documentation environment](local-setup.md) + +## File structure +**Note for translators:** if any of the source files don't exist in your translation, the English content will be used +during the building process. This means that you *must not* place untranslated files in your translation tree. Otherwise, +it will lead to a mess, confusion and may break some tools. + +The structure of the manual sources is hopefully rather intuitive. The most +complicated part is the documentation for extensions, which is also the biggest +part of the manual as all functions are grouped into extensions. + +The documentation for extensions is located in `reference/extension_name/`. For example, +the calendar extension documentation exists in `reference/calendar/`. There you'll find several files: +- *book.xml* - acts as the container for the extension and contains the preface. Other files (like examples.xml) +are included from here. +- *setup.xml* - includes setup, install and configuration documentation +- *constants.xml* - lists all constants that the extension declares, if any +- *configure.xml* - usually this information is in setup.xml, but if the file exists it is magically +included into setup.xml +- *examples.xml* - various examples +- *versions.xml* - contains version information for the extension +- *foo.xml* - example, foo can be anything specific to a topic. Just be sure to include via book.xml. + +A procedural extension (like calendar) also has: +- *reference.xml* - container for the functions, rarely contains any info +- *functions/* - folder with one XML file per function that the extension declares + +And OO extensions (such as imagick) contain: +- *classname.xml* - container for the methods defined by the class, contains also basic info about it +- *classname/* - folder with one XML file per method that the class declares + +Note: *classname* is the lowercased name of the class, not a literal file or directory name. + +There are some other important files: +- *language-defs.ent* - contains local entities used by this language. Some common ones are + the main part titles, but you should also put entities used only by this language's files here. +- *language-snippets.ent* - longer often used XML snippets translated to this language. + Including common warnings, notes, etc. +- *translation.xml* - this file is used to store all central translation info, like a small + intro text for translators and the persons list. This file is not present in the English tree. diff --git a/docs/style.md b/docs/style.md new file mode 100644 index 000000000..c4bbbf801 --- /dev/null +++ b/docs/style.md @@ -0,0 +1,75 @@ +# Style guidelines + +## Technical requirements +- All files **must** be encoded using UTF-8 (without BOM) +- Use only Unix line endings (`\n`) + +## Line lengths +Please aim to keep lines in an XML file around 80 characters long or less. +It is also best to start new sentences on new lines. +These are also known as [Semantic Line Breaks](https://sembr.org). +This aids in keeping *diffs* simple, which is particularly useful for translators. + +## Whitespaces +For XML, indent using one space. Do not use tabs. +PHP and other code in examples may use more spaces for indentation, and +should follow [the coding style for examples](cs-for-examples). + +## Punctuation +Punctuation in the PHP Manual follows regular grammatical rules. +When writing flowing sentences, such as in function descriptions, normal +punctuation should be used. +Lists, titles, and sentence fragments should not be punctuated with +a period. +Sentences need not have two spaces between them. +Commas and apostrophes should be used appropriately. + +## Personalization +The PHP Manual is a technical document, and should be written so. The use of "you" is rampant in the manual, +and presents an unprofessional image. The only exceptions to the personalization rule are: the PHP Tutorial and FAQs. + +Example: +``` +INCORRECT: You can use the optional second parameter to specify tags that should not be stripped. +CORRECT: The optional second parameter may be used to specify tags that should not be stripped. +``` + +## Chronology +- When referring to a specific version of PHP, "since" should not be used. "As of" should be used in this case. +- In changelogs, newer PHP versions go above older ones. +- If a changelog entry applies to multiple PHP versions, separate them by a comma with the lower version first. +Example: `5.2.11, 5.3.1` + +## General Grammar +The PHP Manual should be written with particular attention to general +American English grammar and spelling. +The [serial (Oxford) comma](https://en.wikipedia.org/wiki/Serial_comma) +should be used in a series of three or more terms. +Contractions should be used appropriately. +Special attention should be applied to sentence construction when using +prepositions (i.e., sentences should not end in prepositions). + +## PHP Manual Terms + +There are various phrases and technical terms used throughout the manual where +we try to maintain consistent spelling, formatting, and usage, such as: + +Appropriate Use | Inappropriate Use(s) +-------------------------|-------------------------------------------- +any way | anyway, anyways +appendices | appendixes +built-in | built in, builtin +email | e-mail +[example.com][example] | php.net, google.com +extension | module +PHP 8 | PHP8, PHP-8 +PHP 8.3.0 | PHP 8.3, PHP 8.3.0RC2, PHP 8.0.0BETA, PHP 8.3.0PL1 +superglobals | super globals, autoglobals +web server | webserver +the [Foo Page][example] | [click here][example], go [here][example] +Linux | linux, \*n\*x, \*nix, \*nux, etc +Unix | UNIX (it's a registered trademark) +Windows | windows (when referring to Microsoft Windows) +macOS | MacOS, Mac OS X + +[example]: http://example.com diff --git a/docs/tags-and-entities.md b/docs/tags-and-entities.md new file mode 100644 index 000000000..fa7714c8b --- /dev/null +++ b/docs/tags-and-entities.md @@ -0,0 +1,29 @@ +# Some popular tags and entities + + filenames + constants + variables + a function's parameter/argument + functions, this links to function pages or bolds if + already on the function's page. it also adds (). + + teletype/mono-space font + italics + see HOWTO, includes many other tags. + internal manual links + variables + + external links via global.ent + mmm cookies + + types, this links to the given types manual + page: object -> php.net/types.object + + &return.success; see: language-snippets.ent + &true; TRUE + &false; FALSE + &php.ini; php.ini + +Be sure to check out `entities/global.ent` (in the `doc-base` repo) and +`language-snippets.ent` (located within each language's repo) for more +information for entities and URLs. diff --git a/docs/toc.md b/docs/toc.md new file mode 100644 index 000000000..cf35443a7 --- /dev/null +++ b/docs/toc.md @@ -0,0 +1,19 @@ +## Table of Contents +- [Introduction](README.md) +- [Overview of the build system](overview.md) +- [Contributing to the documentation](contributing.md) +- [Setting up a local build environment](local-setup.md) +- [Editing the PHP Manual](editing.md) +- [Documentation structure](structure.md) +- [Style guidelines](style.md) +- [Coding standard for examples](cs-for-examples.md) +- [Translating documentation](translating.md) +- [Joining the team](joining.md) + +## Appendices +- [FAQ](faq.md) +- [Tools](tools.md) +- [Frequently used tags and entities](tags-and-entities.md) +- [User Note Editing Guidelines](user-notes.md) +- [Setting up a local web development environment](local-web-setup.md) +- [How the released versions are built](public-builds.md) diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 000000000..2963ed17a --- /dev/null +++ b/docs/tools.md @@ -0,0 +1,14 @@ +# Tools + +## Quality Assurance Tools (QA Tools) + +There are various scripts available to ensure the quality of the documentation +and find issues with it, they are located in the `scripts/qa/` directory. + +There might be some more just in `scripts/` but they need to be checked if they +are still relevant and/or given some love. + +## Translation Tools + +There are also various scripts to ensure the quality and synchrony of +documentation translations, located in the `scripts/translation/` directory. diff --git a/docs/translating.md b/docs/translating.md new file mode 100644 index 000000000..904958799 --- /dev/null +++ b/docs/translating.md @@ -0,0 +1,92 @@ +# Translating documentation + +**Watch out:** this chapter describes special parts of the whole editing process. +You will also have to follow other steps from the [editing manual sources](editing.md) section. + +Translating documentation into other languages might look like a complicated +process, but in fact, it's rather simple. + +Because any files that are not yet translated are automatically included +from the English version of the manual when the HTML and other versions +of the translated manual are built, only files that are translated should +be added to the repository for a translation. Untranslated files that +are added to the repository could otherwise become out-of-date and cause +problems with building the translated manual. + +Every file in Git has a *commit hash*. It is basically the current version of +the specified file. We use commit hashes to check if a file is synchronized with its +English counterpart: to find out if the translation is up-to-date. That's why every +file in your translation requires an `EN-Revision` comment with the following syntax: +``` + +``` +The most important part of this comment is the commit hash of the English file +that this translated file is based on. Let's see examples: + +## Translating new file +Say you want to translate the documentation of the `in_array()` function, which +doesn't exist in your language yet. Get the commit hash by changing into the `en` directory and executing the command `git log -n1 --pretty=format:%H -- reference/array/functions/in-array.xml` + +For this example, let's say our commit hash is `68a9c82e06906a5c00e0199307d87dd3739f719b`. Let's see how your translated file header +should look like if we assume that your PHP.net username is *johnsmith*: +``` + + +``` + +The rule is simple: if your revision number is equal to the revision number of +the English file you've translated, then your translation is up-to-date. +Otherwise, it needs to be synced. + +## Updating translation of existing file +Let's assume that you want to update the translation of `password_needs_rehash()`. +One way to see which files require updating, and what has to be +changed to sync with the English version, is to use the [doc.php.net tools](http://doc.php.net). + +Choose your language from the right sidebar and then use the "Outdated files" tool. +Filter files by directory or username (username used here comes from the `Mantainer` +variable in the header comment described above). Let's assume that the tool marked +`password-needs-rehash.xml` as outdated. Click on the filename and you will see +*diff* - list of changes between two versions of file: your version (current +commit hash in `EN-Revision` in your translation) and newest version in the English source +tree. The example below shows what the diff might look like: + +``` +diff --git a/reference/password/functions/password-needs-rehash.xml b/reference/password/functions/password-needs-rehash.xml +index 984eb2dc5c..860758a4a4 100644 +--- a/reference/password/functions/password-needs-rehash.xml ++++ b/reference/password/functions/password-needs-rehash.xml +@@ -12,8 +12,8 @@ + + booleanpassword_needs_rehash + stringhash +- stringalgo +- stringoptions ++ intalgo ++ arrayoptions + + + This function checks to see if the supplied hash implements the algorithm +``` + +As you can see, there is a difference between two lines. The `types` for the +parameters `options` and `algo` in the synopsis had been changed from `string`, +to `int` and `array` respectively. You have to perform these changes in your +translation to make it up-to-date. Open `phpdoc/{LANG}/reference/password/functions/password-needs-rehash.xml` +and change those lines to match the English version. + +Then update the `EN-Revision` commit hash in the header comment. +Your file header might look like this initially: +``` + + +``` +and after changes it should look like this: +``` + + +``` +The new `EN-Revision` commit hash came from the doc tools page. + +Your translation is now up-to-date. It is quite a long process but it's simple +and logical when you get used to it. diff --git a/docs/user-notes.md b/docs/user-notes.md new file mode 100644 index 000000000..bd2cb8d32 --- /dev/null +++ b/docs/user-notes.md @@ -0,0 +1,38 @@ +# User Note Editing Guidelines +These are some guidelines to follow when editing user notes in the manual. + +To begin editing user notes in the manual, you must have a PHP.net account, and you must either: +- Subscribe to the `php-notes` mailing list or newsgroup. As a user submits a new user note, it will appear + as a message on the mailing list with links in the footer of the email that enable you to delete, edit, + or reject that particular note. +- Log on to the server at https://main.php.net/manage/user-notes.php using your PHP.net account username and password. + The user notes administration interface enables you to search for user notes that match particular strings + and edit or change the status of particular notes directly through the Web interface. + +The thing that seems to confuse the most people is the difference between *rejecting* and *deleting* a note. +Basically, they both remove the note from the manual, but *rejecting* sends the user an email about the rejection +with links to support links and other information. Here are some guidelines of when to use each. You can also view +the exact text of the rejection email [here](https://github.com/php/web-master/blob/master/manage/user-notes.php). +- If the note is asking for help (support request, *Does this work...?*, etc.) or if the person is reporting a bug, + *reject* the note. The email will show them the proper place to report such issues. +- If the note contains useful information appropriate for the manual proper, you may incorporate the information + into the manual and then *delete* the note. +- If the note is in the wrong place, incorrect, a giant block of silly, unnecessary code, poorly written, an answer + to another person's question, or just overall confusing, *delete* it. If it was an answer to a question, hunt down + that note and *reject* it. +- If the note is in a language other than English, *delete* the note. +- If the note submitter's email address is obviously bogus, don't *reject* the note, just *delete* it. + Rejecting the note just gives the mail server more work trying to send an email to a non-existent address, + which doesn't help anything. + +If for some reason you need to add to a note, first ask yourself if it's worth it. Make sure you're not answering +a user's question; if you are, then the note doesn't belong there (see above). If you're clarifying a point, see +if it is appropriate to add the clarification to the manual proper; if it is, add it and *delete* the note (see above). +If you still feel that adding your addition to the note will be the best option, then go ahead and add it. Usually, editors +add their note in a "Editor's Note" block at the top. Unless you are correcting a minor error, make it obvious that you edited the note. + +If you have some free time and commit access to phpdoc, try going through some of the manual pages and adding some of +the better notes into the documentation proper. Be sure to *delete* these notes after they're implemented. + +If you are in doubt about what to do with a note, you may ask for help on the `php-notes` mailing list (or `phpdoc`, +if what you're doing involves the documentation proper). diff --git a/entities/global.ent b/entities/global.ent index fa0d92f51..74766de53 100644 --- a/entities/global.ent +++ b/entities/global.ent @@ -354,7 +354,7 @@ - + diff --git a/scripts/revcheck.php b/scripts/revcheck.php index 2decae22d..34c9f14aa 100644 --- a/scripts/revcheck.php +++ b/scripts/revcheck.php @@ -33,7 +33,7 @@ [translation] must be a valid git checkout directory of a translation. Read more about revision comments and related functionality in the - PHP Documentation Howto: http://doc.php.net/tutorial/ + PHP Documentation Howto: https://doc.php.net/guide/ USAGE; diff --git a/RFC/skeletons/book.xml b/skeletons/book.xml similarity index 100% rename from RFC/skeletons/book.xml rename to skeletons/book.xml diff --git a/RFC/skeletons/classname.xml b/skeletons/classname.xml similarity index 100% rename from RFC/skeletons/classname.xml rename to skeletons/classname.xml diff --git a/RFC/skeletons/configure.xml b/skeletons/configure.xml similarity index 100% rename from RFC/skeletons/configure.xml rename to skeletons/configure.xml diff --git a/RFC/skeletons/constants.xml b/skeletons/constants.xml similarity index 100% rename from RFC/skeletons/constants.xml rename to skeletons/constants.xml diff --git a/RFC/skeletons/examples.xml b/skeletons/examples.xml similarity index 100% rename from RFC/skeletons/examples.xml rename to skeletons/examples.xml diff --git a/RFC/skeletons/exceptionname.xml b/skeletons/exceptionname.xml similarity index 100% rename from RFC/skeletons/exceptionname.xml rename to skeletons/exceptionname.xml diff --git a/RFC/skeletons/function.xml b/skeletons/function.xml similarity index 100% rename from RFC/skeletons/function.xml rename to skeletons/function.xml diff --git a/RFC/skeletons/ini.xml b/skeletons/ini.xml similarity index 100% rename from RFC/skeletons/ini.xml rename to skeletons/ini.xml diff --git a/RFC/skeletons/method.xml b/skeletons/method.xml similarity index 100% rename from RFC/skeletons/method.xml rename to skeletons/method.xml diff --git a/RFC/skeletons/reference.xml b/skeletons/reference.xml similarity index 100% rename from RFC/skeletons/reference.xml rename to skeletons/reference.xml diff --git a/RFC/skeletons/setup.xml b/skeletons/setup.xml similarity index 100% rename from RFC/skeletons/setup.xml rename to skeletons/setup.xml diff --git a/RFC/skeletons/versions.xml b/skeletons/versions.xml similarity index 100% rename from RFC/skeletons/versions.xml rename to skeletons/versions.xml