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

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: [email protected].
\ 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 `[email protected]` 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