diff --git a/tutorial/builds.md b/tutorial/builds.md index c7e1930..120ae4c 100644 --- a/tutorial/builds.md +++ b/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 diff --git a/tutorial/editing.md b/tutorial/editing.md index 9ba0a2b..b906388 100644 --- a/tutorial/editing.md +++ b/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. diff --git a/tutorial/faq.md b/tutorial/faq.md index 9b8f10a..ae7b2ab 100644 --- a/tutorial/faq.md +++ b/tutorial/faq.md @@ -18,8 +18,8 @@ temporary often becomes permanent. ## 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. +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. ## Is there an online editor? @@ -37,11 +37,11 @@ Add the `role="noversion"` to its ``. 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: ``` - + ``` Then you can use this syntax in the documentation: ``` -google spec +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. @@ -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. diff --git a/tutorial/style.md b/tutorial/style.md index b4ff125..98984dc 100644 --- a/tutorial/style.md +++ b/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 \ No newline at end of file diff --git a/tutorial/user-notes.md b/tutorial/user-notes.md index 4dba5a0..b292c30 100644 --- a/tutorial/user-notes.md +++ b/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.