com web/doc: First draft of tutorial for contributors: tutorial/editing.md tutorial/faq.md tutorial/intro.md tutorial/joining.md tutorial/structure.md
tutorial/style.md
| From: | sobak@php.net | Date: | Sun, 15 Jun 2014 20:25:56 +0000 |
| Subject: | com web/doc: First draft of tutorial for contributors: tutorial/editing.md tutorial/faq.md tutorial/intro.md tutorial/joining.md tutorial/structure.md tutorial/style.md |
||
| Groups: | php.doc.web | ||
| Request: | Send a blank email to doc-web+get-2360@lists.php.net to get a copy of this message | ||
Commit: eb3aeee896d1dffc705adedb1fa5ad8e9633f1ba
Author: Sobak <msobaczewski@gmail.com> Sun, 15 Jun 2014 22:25:56 +0200
Parents: 206c0f43c35ed0d68251d11b87cdd5b39800a908
Branches: master
Link: http://git.php.net/?p=web/doc.git;a=commitdiff;h=eb3aeee896d1dffc705adedb1fa5ad8e9633f1ba
Log:
First draft of tutorial for contributors
Work in progress obviously, read more here:
http://news.php.net/php..doc/969384992
Changed paths:
A tutorial/editing.md
A tutorial/faq.md
A tutorial/intro.md
A tutorial/joining.md
A tutorial/structure.md
A tutorial/style.md
diff --git a/tutorial/editing.md b/tutorial/editing.md new file mode 100644 index 0000000..004af9f --- /dev/null +++ b/tutorial/editing.md @@ -0,0 +1,132 @@ +# Editing manual sources + +## Introduction +When editing or translating manual you have to remember some things: +- use only UTF-8 encoding +- follow [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 couple of options. Either way, the generated (or copied) files +will need to be filled out. + +### Option A: Copy skeleton files +This involves copying the skeleton files into the correct location: +``` +cp /phpdoc/RFC/skeletons/method.xml classname/methodname.xml (for new methods) +cp /phpdoc/RFC/skeletons/function.xml functions/functionname.xml (for new functions) +``` + +Note: *classname*, *methodname* and *functionname* are lowercased names of the class, method or function, respectively, +not a literal file name. + +### Option B: Generating files using docgen +The `docgen` script is found within the PHP documentation (phpdoc/scripts/docgen/) and uses Reflection to generate +documentation (DocBook) files. Fill in skeleton files before you commit them! + +## Translating documentation +Translating documentation into other languages might look like a complicated process, but in fact, it's rather simple. +Every file in SVN has *revision*. It is basically current version of specified file. We use revisions to check if file +is synchronized with English version, so to find out if translation is up-to-date. That's why every file in your +translation requires EN-Revision comment with following syntax: +`<!-- EN-Revision: [some number] Maintainer: [username] Status: ready -->` +The most important part of this comment is revision of English file which translated version is based on. Let's see +examples: + +### Translating new file +You want to translate documentation of `in_array()` function, which doesn't exists in your language yet. Open the file +`phpdoc/en/reference/array/in-array.xml` and copy number of revision. Sample header might look like this: +``` +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 310394 $ --> +``` + +So our number is `310394`. Let's see how your translated file header should look like if we assume that your SVN +username is *johnsmith*: +``` +<?xml version="1.0" encoding="utf-8"?> +<!-- EN-Revision: 310394 Maintainer: johnsmith Status: ready --> +<!-- $Revision$ --> +``` + +`$Revision` is a kind of macro which will be replaced with number of current revision when you commit your changes. +Revision number you have copied from english file was created this way. + +The rule is simple: if your revision number is equal to revision number of english file you've translated, it means +that your translation is up-to-date. Otherwise, it needs to be synced. + +### Updating translation of existing file +Let's assume you want to update translation of `password_needs_rehash()`. There are two simple ways +to see which files require update and what have to be changed to sync with English version: using +[Online Editor](http://doc.php.net) or [doc.php.net tools](http://doc.php.net). Second way is described below. + +Choose your language from right sidebar and then use "Outdated files" tool. Filter files by directory or username +(username used here comes from `Mantainer` variable in comment described below). Let's assume that script marked +`password-needs-rehash.xml` as outdated. Click on filename and you will see *diff* - list of changes between two +versions of file: your version (current number in EN-Revision in your translation) and newest version in English +tree. This is sample diff: + +``` +--- phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2013/06/21 12:24:55 330609 ++++ phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2014/03/24 20:23:27 333093 +@@ -12,8 +12,8 @@ + <methodsynopsis> + <type>boolean</type><methodname>password_needs_rehash</methodname> + <methodparam><type>string</type><parameter>hash</parameter></methodparam> +- <methodparam><type>string</type><parameter>algo</parameter></methodparam> +- <methodparam choice="opt"><type>string</type><parameter>options</parameter></methodparam> ++ <methodparam><type>integer</type><parameter>algo</parameter></methodparam> ++ <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam> + </methodsynopsis> + <para> + This function checks to see if the supplied hash implements the algorithm +``` + +First two lines indicate compared revisions. First was taken from your EN-Revision tag and second is current version +of this file in English. As you can see, there is a difference between two lines. Types of parameters `options` and +`algo` in function synopsis had been changed from `string` to `integer` and `array`. You have to perform this 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 English version. + +Then update EN-Revision number in header. You can also add your credits using CREDITS tag. Your file header might look like this: +``` +<?xml version="1.0" encoding="utf-8"?> +<!-- EN-Revision: 330609 Maintainer: someone Status: ready --> +<!-- $Revision: 123456$ --> +``` +and after changes it should looke like this: +``` +<?xml version="1.0" encoding="utf-8"?> +<!-- EN-Revision: 333093 Maintainer: someone Status: ready --> +<!-- $Revision$ --> +<!-- CREDITS: johnsmith --> +``` +Numbers came from diff showed below. If you want to add yourself to credits tag which already exists, separate +usernames with coma, i.e.: `<!-- CREDITS: george, johnsmith -->`. + +Finally, your translation is up-to-date. It is quite long process but it's simple and logical when you get used to. + +## Validating your changes +Every time you make changes to documentation sources (both English or translation) you have to validate your changes. +Proper script is distributed with documentation sources, so you already have it in *doc-base* directory. 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 whole lang parameter and only execute `php configure.php`. 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 access to SVN, you can commit modified files. + +## Viewing changes online +Documentation is builded every Friday. It applies to all formats - online, offline HTML files and CHM. However, +there is a special mirror - http://docs.php.net/ - where manual is updated from sources every six hours. If any +errors occured, special message will be delivered to your mailinglist (`doc-{LANG}` for translations and `doc` for +English manual). + +Last chapter contains [style guidelines](style.md) you are obliged to follow. Read them carefully. \ No newline at end of file diff --git a/tutorial/faq.md b/tutorial/faq.md new file mode 100644 index 0000000..3a25efe --- /dev/null +++ b/tutorial/faq.md @@ -0,0 +1,94 @@ +# Frequently Asked Questions + +## If a <refentry> should not emit versioning information, what should I do? +Add the `role="noversion"` to its `<refentry>`. Example: `<refentry xml:id="reserved.variables.argc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion//">` + +## How do I add a link to a method? +Use `<methodname>Class::Method</methodname>` Note that the case does not matter when adding a link. + +## 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: +``` +<!ENTITY spec.google "http://www.google.com/"> +``` +Then you can use this syntax in documentation: +``` +<link xlink:href="&spec.google;">google spec</link> +``` +Be sure the file understands the namespace with `xmlns:xlink="http://www.w3.org/1999/xlink"` in the root element. + +## I made a change to a file but want to revert this change, how? +To merge a file to the previous state use `svn merge -rHEAD:PREV filename.xml`, then commit your changes. + +## 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 following command: +`$ php docgen.php -e simplexml -o outdir`. It creates the skeletons that you edit 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, you can't. Edit files before commit. There are two reasons: translators and the fact that temporary +often becomes permanent, and bogus text is not good. + +## Running configure.php ends up Segfaulting, what is up? +There are bugs with certain versions of libxml that cause this, so hacks exist to get around it. +To execute the hack, pass in: `$ php configure.php --disable-segfault-error`. +Note: This disables some error checking and beautification but raw errors will be shown. +Note: Usually the problem is a major XML syntax issue. + +## In the changelog, which order do the PHP versions go? +Newest PHP versions go above the older ones. + +## In the changelog, a change happened in two PHP versions. How do I enter this? +Multiple versions are separated by a comma, with the lesser version first. Example: `<entry>5.2.11, 5.3.1</entry>` + +## When adding a <note>, should I add a <title>? +Typically titles are useful for notes, but it's not required. Syntax as follows: +``` +<note> + <title>foo</title> + <para>note contents</para> +</note> +``` + +## 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: `phpdoc/en/extname/version.xml` +Changes to functions, like added parameters, are documented within changelogs for each page +Example text: **Feature X has been available since PHP X.Y.Z**. + +## A parameter is optional, how is it documented? +Like normal, except `methodparam` receives the `choice="opt"` attribute, and the `<initializer>` tag is used +to signify the default value. Example syntax: +``` +<methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam> +``` + +## Do I need to edit these entities* files? +No, these are auto-generated by the configure process, also do not commit them. +Examples: `entities/file-entities.ent` and `en/reference/foo/entities.bar.xml` + +## Is there an online editor? +Yes, just go to https://edit.php.net + +## How often is the documentation built? +Weekly, but there is special mirror - https://doc.php.net - where documentation is build every six hours. + +## 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? Or undocumented (proto only) documentation? +Missing functions (no associated XML files) can be found like so (assuming a doc checkout, and PhD is installed): +``` +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 +``` + +## What .subversion/config settings should I have set? +``` +*.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL +``` \ No newline at end of file diff --git a/tutorial/intro.md b/tutorial/intro.md new file mode 100644 index 0000000..291062e --- /dev/null +++ b/tutorial/intro.md @@ -0,0 +1,27 @@ +# PHP Manual Contribution Guide +This document is in very early stage of development. If you are a newomer, please look at already existing resources. +More experienced users are welcome to contribute. + +## Introduction +PHP is well known for having excellent documentation, documentation that is created by volunteers who +collectively make changes every day. This guide is designed for people who work on the official PHP documentation. + +## Glossary +This guide use some terminology you have to know. Don't worry, it's easy: +- **editor** - person who contributes to original english manual +- **translator** - person who translates english manual into another language +- **{LANG}** - replace it with your country code, in example in mailing list address (note: Brazilian Portuguese +format differs from the rest and it's called *pt_BR* for SVN module and *pt-br* for mailing list sufix) + +## Table of Contents +- [Joining the team](joining.md) +- [Documentation structure](structure.md) +- [Editing PHP Manual](editing.md) +- [Style guidelines](style.md) + +## Appendices +- [FAQ](faq.md) + +## Feedback +Feedback is most certainly welcome on this document. Without your submissions and input, this document wouldn't exist. +Please send your additions, comments and criticisms to the following email address: phpdoc@lists.php.net. \ No newline at end of file diff --git a/tutorial/joining.md b/tutorial/joining.md new file mode 100644 index 0000000..92fe49c --- /dev/null +++ b/tutorial/joining.md @@ -0,0 +1,28 @@ +# Joining the team +Joining the PHP Documentation team is a simple process, but a process nonetheless. It can be summarized as: + +## Write a list +Because official communication is done there, you should write the proper list. Say “Hi” and what you're interested +in doing. You may feel more comfortable lurking for awhile, or reading the archives, or hanging out in IRC +(#php.doc on Efnet) for awhile, but ultimately let the list know who you are. + +### For editors +You should send your message to `phpdoc@lists.php.net` mailinglist. + +### For translators +You should send your message to `doc-{LANG}@lists.php.net` mailinglist. + +## 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 the [Online Documentation Editor](https://wiki.php.net/doc/editor) +which allows you to login via Facebook/Twitter/Google account and edit documentation. Your patches will be then +reviewed and accepted by someone with SVN access. + +## Obtaining SVN access +If you plan to contribute to manual regularly and want to do this more efficiently, you probably would like to +use SVN directly. To request for PHP.net account, please fill in [this form](http://php.net/git-php.php). Provide links +to your commits or list your patches on textarea field. Basically, tell us what have done, to prove that you really +need this account. + +Next chapter will explain how to get manual sources and how are they [structured](structure.md). \ No newline at end of file diff --git a/tutorial/structure.md b/tutorial/structure.md new file mode 100644 index 0000000..1bbddbe --- /dev/null +++ b/tutorial/structure.md @@ -0,0 +1,48 @@ +# Manual sources structure + +## Downloading sources +PHP Manual sources are currently stored in Subversion (SVN) repository. You don't need SVN access to checkout (download) +them, but you need it if you want to send your changes to our server. + +This tutorial assumes that you have basic knowledge about SVN. If not, you can read {TODO}. In order to checkout manual +files, use following command: + +### For editors +`svn checkout https://svn.php.net/repository/phpdoc/modules/doc-en phpdoc` + +### For translators +`svn checkout https://svn.php.net/repository/phpdoc/modules/doc-{LANG} phpdoc` + +Both commands will create directory named phpdoc, however, the name can be anything you wish. This directory will +contain folder with sources of your language (named *{LANG}*) and *doc-base* with some helpful tools. + +## Files structure +**Note for translators: ** if any of source files doesn't exists in translation, English file will be used +while building process. This means that you *cannot* place untranslated files in your translation tree. Otherwise, +it will lead to mess, confusion and may break some tools. + +Structure of manual sources is rather intuitive. The most complicated part is documentation for extensions +(which is the biggest part of manual, because all functions are grouped into extensions). + +The documentation for extensions is located in `/phpdoc/{LANG}/reference/extension_name/`. For example, +the calendar extension documentation exists in `/phpdoc/{LANG}/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 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 +- *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 per method that the class declares + +Note: *classname* is the lowercased name of the class, not a literal file or directory name. + +Next chapter will discuss how to [edit manual sources](editing.md). \ No newline at end of file diff --git a/tutorial/style.md b/tutorial/style.md new file mode 100644 index 0000000..97d720c --- /dev/null +++ b/tutorial/style.md @@ -0,0 +1,8 @@ +# Style guidelines + +TODO: +- UTF-8 +- whitespaces +- formal style +- common mistakes and conventions specific to php manual (https://wiki.php.net/doc/howto/styleguide) +- something else? \ No newline at end of file
diff --git a/tutorial/editing.md b/tutorial/editing.md new file mode 100644 index 0000000..004af9f --- /dev/null +++ b/tutorial/editing.md @@ -0,0 +1,132 @@ +# Editing manual sources + +## Introduction +When editing or translating manual you have to remember some things: +- use only UTF-8 encoding +- follow [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 couple of options. Either way, the generated (or copied) files +will need to be filled out. + +### Option A: Copy skeleton files +This involves copying the skeleton files into the correct location: +``` +cp /phpdoc/RFC/skeletons/method.xml classname/methodname.xml (for new methods) +cp /phpdoc/RFC/skeletons/function.xml functions/functionname.xml (for new functions) +``` + +Note: *classname*, *methodname* and *functionname* are lowercased names of the class, method or function, respectively, +not a literal file name. + +### Option B: Generating files using docgen +The `docgen` script is found within the PHP documentation (phpdoc/scripts/docgen/) and uses Reflection to generate +documentation (DocBook) files. Fill in skeleton files before you commit them! + +## Translating documentation +Translating documentation into other languages might look like a complicated process, but in fact, it's rather simple. +Every file in SVN has *revision*. It is basically current version of specified file. We use revisions to check if file +is synchronized with English version, so to find out if translation is up-to-date. That's why every file in your +translation requires EN-Revision comment with following syntax: +`<!-- EN-Revision: [some number] Maintainer: [username] Status: ready -->` +The most important part of this comment is revision of English file which translated version is based on. Let's see +examples: + +### Translating new file +You want to translate documentation of `in_array()` function, which doesn't exists in your language yet. Open the file +`phpdoc/en/reference/array/in-array.xml` and copy number of revision. Sample header might look like this: +``` +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 310394 $ --> +``` + +So our number is `310394`. Let's see how your translated file header should look like if we assume that your SVN +username is *johnsmith*: +``` +<?xml version="1.0" encoding="utf-8"?> +<!-- EN-Revision: 310394 Maintainer: johnsmith Status: ready --> +<!-- $Revision$ --> +``` + +`$Revision` is a kind of macro which will be replaced with number of current revision when you commit your changes. +Revision number you have copied from english file was created this way. + +The rule is simple: if your revision number is equal to revision number of english file you've translated, it means +that your translation is up-to-date. Otherwise, it needs to be synced. + +### Updating translation of existing file +Let's assume you want to update translation of `password_needs_rehash()`. There are two simple ways +to see which files require update and what have to be changed to sync with English version: using +[Online Editor](http://doc.php.net) or [doc.php.net tools](http://doc.php.net). Second way is described below. + +Choose your language from right sidebar and then use "Outdated files" tool. Filter files by directory or username +(username used here comes from `Mantainer` variable in comment described below). Let's assume that script marked +`password-needs-rehash.xml` as outdated. Click on filename and you will see *diff* - list of changes between two +versions of file: your version (current number in EN-Revision in your translation) and newest version in English +tree. This is sample diff: + +``` +--- phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2013/06/21 12:24:55 330609 ++++ phpdoc/en/trunk/reference/password/functions/password-needs-rehash.xml 2014/03/24 20:23:27 333093 +@@ -12,8 +12,8 @@ + <methodsynopsis> + <type>boolean</type><methodname>password_needs_rehash</methodname> + <methodparam><type>string</type><parameter>hash</parameter></methodparam> +- <methodparam><type>string</type><parameter>algo</parameter></methodparam> +- <methodparam choice="opt"><type>string</type><parameter>options</parameter></methodparam> ++ <methodparam><type>integer</type><parameter>algo</parameter></methodparam> ++ <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam> + </methodsynopsis> + <para> + This function checks to see if the supplied hash implements the algorithm +``` + +First two lines indicate compared revisions. First was taken from your EN-Revision tag and second is current version +of this file in English. As you can see, there is a difference between two lines. Types of parameters `options` and +`algo` in function synopsis had been changed from `string` to `integer` and `array`. You have to perform this 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 English version. + +Then update EN-Revision number in header. You can also add your credits using CREDITS tag. Your file header might look like this: +``` +<?xml version="1.0" encoding="utf-8"?> +<!-- EN-Revision: 330609 Maintainer: someone Status: ready --> +<!-- $Revision: 123456$ --> +``` +and after changes it should looke like this: +``` +<?xml version="1.0" encoding="utf-8"?> +<!-- EN-Revision: 333093 Maintainer: someone Status: ready --> +<!-- $Revision$ --> +<!-- CREDITS: johnsmith --> +``` +Numbers came from diff showed below. If you want to add yourself to credits tag which already exists, separate +usernames with coma, i.e.: `<!-- CREDITS: george, johnsmith -->`. + +Finally, your translation is up-to-date. It is quite long process but it's simple and logical when you get used to. + +## Validating your changes +Every time you make changes to documentation sources (both English or translation) you have to validate your changes. +Proper script is distributed with documentation sources, so you already have it in *doc-base* directory. 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 whole lang parameter and only execute `php configure.php`. 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 access to SVN, you can commit modified files. + +## Viewing changes online +Documentation is builded every Friday. It applies to all formats - online, offline HTML files and CHM. However, +there is a special mirror - http://docs.php.net/ - where manual is updated from sources every six hours. If any +errors occured, special message will be delivered to your mailinglist (`doc-{LANG}` for translations and `doc` for +English manual). + +Last chapter contains [style guidelines](style.md) you are obliged to follow. Read them carefully. \ No newline at end of file diff --git a/tutorial/faq.md b/tutorial/faq.md new file mode 100644 index 0000000..3a25efe --- /dev/null +++ b/tutorial/faq.md @@ -0,0 +1,94 @@ +# Frequently Asked Questions + +## If a <refentry> should not emit versioning information, what should I do? +Add the `role="noversion"` to its `<refentry>`. Example: `<refentry xml:id="reserved.variables.argc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion//">` + +## How do I add a link to a method? +Use `<methodname>Class::Method</methodname>` Note that the case does not matter when adding a link. + +## 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: +``` +<!ENTITY spec.google "http://www.google.com/"> +``` +Then you can use this syntax in documentation: +``` +<link xlink:href="&spec.google;">google spec</link> +``` +Be sure the file understands the namespace with `xmlns:xlink="http://www.w3.org/1999/xlink"` in the root element. + +## I made a change to a file but want to revert this change, how? +To merge a file to the previous state use `svn merge -rHEAD:PREV filename.xml`, then commit your changes. + +## 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 following command: +`$ php docgen.php -e simplexml -o outdir`. It creates the skeletons that you edit 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, you can't. Edit files before commit. There are two reasons: translators and the fact that temporary +often becomes permanent, and bogus text is not good. + +## Running configure.php ends up Segfaulting, what is up? +There are bugs with certain versions of libxml that cause this, so hacks exist to get around it. +To execute the hack, pass in: `$ php configure.php --disable-segfault-error`. +Note: This disables some error checking and beautification but raw errors will be shown. +Note: Usually the problem is a major XML syntax issue. + +## In the changelog, which order do the PHP versions go? +Newest PHP versions go above the older ones. + +## In the changelog, a change happened in two PHP versions. How do I enter this? +Multiple versions are separated by a comma, with the lesser version first. Example: `<entry>5.2.11, 5.3.1</entry>` + +## When adding a <note>, should I add a <title>? +Typically titles are useful for notes, but it's not required. Syntax as follows: +``` +<note> + <title>foo</title> + <para>note contents</para> +</note> +``` + +## 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: `phpdoc/en/extname/version.xml` +Changes to functions, like added parameters, are documented within changelogs for each page +Example text: **Feature X has been available since PHP X.Y.Z**. + +## A parameter is optional, how is it documented? +Like normal, except `methodparam` receives the `choice="opt"` attribute, and the `<initializer>` tag is used +to signify the default value. Example syntax: +``` +<methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>false</initializer></methodparam> +``` + +## Do I need to edit these entities* files? +No, these are auto-generated by the configure process, also do not commit them. +Examples: `entities/file-entities.ent` and `en/reference/foo/entities.bar.xml` + +## Is there an online editor? +Yes, just go to https://edit.php.net + +## How often is the documentation built? +Weekly, but there is special mirror - https://doc.php.net - where documentation is build every six hours. + +## 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? Or undocumented (proto only) documentation? +Missing functions (no associated XML files) can be found like so (assuming a doc checkout, and PhD is installed): +``` +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 +``` + +## What .subversion/config settings should I have set? +``` +*.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL +``` \ No newline at end of file diff --git a/tutorial/intro.md b/tutorial/intro.md new file mode 100644 index 0000000..291062e --- /dev/null +++ b/tutorial/intro.md @@ -0,0 +1,27 @@ +# PHP Manual Contribution Guide +This document is in very early stage of development. If you are a newomer, please look at already existing resources. +More experienced users are welcome to contribute. + +## Introduction +PHP is well known for having excellent documentation, documentation that is created by volunteers who +collectively make changes every day. This guide is designed for people who work on the official PHP documentation. + +## Glossary +This guide use some terminology you have to know. Don't worry, it's easy: +- **editor** - person who contributes to original english manual +- **translator** - person who translates english manual into another language +- **{LANG}** - replace it with your country code, in example in mailing list address (note: Brazilian Portuguese +format differs from the rest and it's called *pt_BR* for SVN module and *pt-br* for mailing list sufix) + +## Table of Contents +- [Joining the team](joining.md) +- [Documentation structure](structure.md) +- [Editing PHP Manual](editing.md) +- [Style guidelines](style.md) + +## Appendices +- [FAQ](faq.md) + +## Feedback +Feedback is most certainly welcome on this document. Without your submissions and input, this document wouldn't exist. +Please send your additions, comments and criticisms to the following email address: phpdoc@lists.php.net. \ No newline at end of file diff --git a/tutorial/joining.md b/tutorial/joining.md new file mode 100644 index 0000000..92fe49c --- /dev/null +++ b/tutorial/joining.md @@ -0,0 +1,28 @@ +# Joining the team +Joining the PHP Documentation team is a simple process, but a process nonetheless. It can be summarized as: + +## Write a list +Because official communication is done there, you should write the proper list. Say “Hi” and what you're interested +in doing. You may feel more comfortable lurking for awhile, or reading the archives, or hanging out in IRC +(#php.doc on Efnet) for awhile, but ultimately let the list know who you are. + +### For editors +You should send your message to `phpdoc@lists.php.net` mailinglist. + +### For translators +You should send your message to `doc-{LANG}@lists.php.net` mailinglist. + +## 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 the [Online Documentation Editor](https://wiki.php.net/doc/editor) +which allows you to login via Facebook/Twitter/Google account and edit documentation. Your patches will be then +reviewed and accepted by someone with SVN access. + +## Obtaining SVN access +If you plan to contribute to manual regularly and want to do this more efficiently, you probably would like to +use SVN directly. To request for PHP.net account, please fill in [this form](http://php.net/git-php.php). Provide links +to your commits or list your patches on textarea field. Basically, tell us what have done, to prove that you really +need this account. + +Next chapter will explain how to get manual sources and how are they [structured](structure.md). \ No newline at end of file diff --git a/tutorial/structure.md b/tutorial/structure.md new file mode 100644 index 0000000..1bbddbe --- /dev/null +++ b/tutorial/structure.md @@ -0,0 +1,48 @@ +# Manual sources structure + +## Downloading sources +PHP Manual sources are currently stored in Subversion (SVN) repository. You don't need SVN access to checkout (download) +them, but you need it if you want to send your changes to our server. + +This tutorial assumes that you have basic knowledge about SVN. If not, you can read {TODO}. In order to checkout manual +files, use following command: + +### For editors +`svn checkout https://svn.php.net/repository/phpdoc/modules/doc-en phpdoc` + +### For translators +`svn checkout https://svn.php.net/repository/phpdoc/modules/doc-{LANG} phpdoc` + +Both commands will create directory named phpdoc, however, the name can be anything you wish. This directory will +contain folder with sources of your language (named *{LANG}*) and *doc-base* with some helpful tools. + +## Files structure +**Note for translators: ** if any of source files doesn't exists in translation, English file will be used +while building process. This means that you *cannot* place untranslated files in your translation tree. Otherwise, +it will lead to mess, confusion and may break some tools. + +Structure of manual sources is rather intuitive. The most complicated part is documentation for extensions +(which is the biggest part of manual, because all functions are grouped into extensions). + +The documentation for extensions is located in `/phpdoc/{LANG}/reference/extension_name/`. For example, +the calendar extension documentation exists in `/phpdoc/{LANG}/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 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 +- *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 per method that the class declares + +Note: *classname* is the lowercased name of the class, not a literal file or directory name. + +Next chapter will discuss how to [edit manual sources](editing.md). \ No newline at end of file diff --git a/tutorial/style.md b/tutorial/style.md new file mode 100644 index 0000000..97d720c --- /dev/null +++ b/tutorial/style.md @@ -0,0 +1,8 @@ +# Style guidelines + +TODO: +- UTF-8 +- whitespaces +- formal style +- common mistakes and conventions specific to php manual (https://wiki.php.net/doc/howto/styleguide) +- something else? \ No newline at end of file