Various updates

tutorial/builds.md

@@ -4,7 +4,7 @@ The PHP Manual is written in [DocBook][docbook] and built by [PhD][phd], and
 these builds are rsynced to the mirrors for users to use.
 
 ## Mirror builds
-The [rsync box][rsync.php.net] builds the manuals every night, at around 23:00 CST.
+The [rsync box][rsync.php.net] builds the manuals every night, at around 5:00 UTC.
 The mirrors then pick up these builds when they sync, which usually happens every hour.
 When a mirror syncs depends on how its cron is set up.
 
@@ -26,10 +26,16 @@ for a language, another way to check if the docs validated is by looking at buil
 dates on the doc server. See "Doc server builds", above.
 
 ## Additional notes
-- If a manual does not validate on Friday, it will not be pushed to the mirrors
-  until it does validate (hopefully, the upcoming Friday).
-- Only active translations are selectable/downloadable, and this is managed in
-  [phpweb/includes/languages.inc][languages.inc]
+- If a manual does not validate on some day, it will not be pushed to the mirrors
+  until it does validate (hopefully, the next day).
+- Only active translations are bulit on rsync box (and then pushed to regular
+  mirrors). This is managed in [web/php/includes/languages.inc][languages.inc]
+- [docs.php.net][docs.php.net] attempts to build all translations (both active)
+  and inactive.
+
+  However, we use `broken-language.txt` file in root of broken
+  translations to disable those very outdated and failing to build
+  for a long time.
 
 ## The humans who manage these
 If there is a problem with the synced builds, it's wise to contact

tutorial/editing.md

@@ -1,9 +1,8 @@
 # Editing manual sources
 
 ## Introduction
-When editing or translating the manual, you have to remember some things:
-- use only UTF-8 encoding
-- follow the project's [style guidelines](style.php)
+Before making any changes to the manual - either English version ore
+translation, make sure you read [style guidelines](style.php)!
 
 ## Editing existing documentation
 Simply open the files and edit them.

tutorial/faq.md

@@ -37,11 +37,11 @@ Add the `role="noversion"` to its `<refentry>`. Example:
 ## 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/">
+<!ENTITY url.google "http://www.google.com/">
 ```
 Then you can use this syntax in the documentation:
 ```
-<link xlink:href="&spec.google;">google spec</link>
+Check out <link xlink:href="&url.google;">Google</link>
 ```
 Be sure the file understands the `xlink` namespace, by using `xmlns:xlink="http://www.w3.org/1999/xlink"` in the document element.
 
@@ -82,8 +82,9 @@ phd --docbook doc-base/.manual.xml --package PHP --format php
 php doc-base/scripts/check-missing-docs.php -d output/index.sqlite
 ```
 
-## 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.
+## After fixing a build, translation is still not updated on docs server and there are no errors shown
+If you just fixed the build of an old translation, it works locally, but it's not updated on the docs
+mirror, make sure that you removed `broken-language.txt` from the root of your translation.
 
 ## Do I need to edit these entities* files?
 No, these are auto-generated by the configure process, also do not commit them.

tutorial/style.md

@@ -49,15 +49,16 @@ Appropriate Use          | Inappropriate Use(s)
 any way                  | anyway, anyways
 appendices               | appendixes
 built-in                 | built in, builtin
-command line             | commandline, CLI
 email                    | e-mail
-example.com              | php.net, google.com
+[example.com][example]   | php.net, google.com
 extension                | module
 Linux                    | linux, *n*x, *nix, *nux, etc
 PHP 5                    | PHP5, PHP-5
 PHP 4.3.0                | PHP 4.3, PHP 4.3.0RC2, PHP 5.0.0BETA, PHP 4.3.0PL1
 superglobals             | super globals, autoglobals
 web server               | webserver
-the foo page (as a link) | click here, go here
+the [Foo Page][example]  | [click here][example], go [here][example]
 Unix                     | UNIX (it's a registered trademark)
 Windows                  | windows (when referring to Microsoft Windows)
+
+[example]: http://example.com

tutorial/user-notes.md

@@ -2,9 +2,9 @@
 These are some guidelines to follow when editing user notes in the manual.
 
 To begin editing user notes in the manual, you must have SVN commit access to the manual, and you must either:
-- Subscribe to the php-notes mailing list or newsgroup as described at Mailing Lists, Newsgroups and SVN Modules.
-  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.
+- 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 http://master.php.net/manage/user-notes.php using your SVN user ID 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.
@@ -27,7 +27,9 @@ the exact text of the rejection email [here](http://git.php.net/?p=web/master.gi
 
 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 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.