com web/doc: Clarified the download section: tutorial/structure.md

Commit: 38fa42515932bd5e5d9fa1df138effb0a140a395 Author: Philip Olson <philip@roshambo.org> Thu, 14 Sep 2017 12:16:55 -0700 Committer: GitHub <noreply@github.com> Thu, 14 Sep 2017 12:16:55 -0700 Parents: f4aa155a0ea348133b879459e2b613c1f12441c5 Branches: master Link: http://git.php.net/?p=web/doc.git;a=commitdiff;h=38fa42515932bd5e5d9fa1df138effb0a140a395 Log: Clarified the download section Clarified the download section to include additional information and examples, including information about svn externals. Changed paths: M tutorial/structure.md Diff: diff --git a/tutorial/structure.md b/tutorial/structure.md index 2b6b851..a2ffe3b 100644 --- a/tutorial/structure.md +++ b/tutorial/structure.md @@ -1,26 +1,49 @@ # Manual sources structure -## Downloading sources +## Downloading the PHP Documentation Source The PHP Manual sources are currently stored in our Subversion (SVN) repository. You don't need SVN access to checkout (download) the files, but you do 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 [Version Control with Subversion](http://svnbook.red-bean.com/). -In order to checkout the manual files, use the following command: +This tutorial assumes that you have basic terminal and Subversion knowledge, although +don't worry if you've never used Subversion as only basic commands are used, and our +setup is simple (e.g., no branches). + +To checkout the documentation source, use a modified version of the following command +where you change {LANG} to a desired language, such as en for only English: + +``` +svn checkout https://svn.php.net/repository/phpdoc/modules/doc-{LANG} phpdoc-{LANG} +``` + +This command creates a directory named phpdoc-{LANG} because the source is +the first 'svn checkout' argument, and the second argument defines the directory name +that stores the checked out directories and files (this name can be anything you wish). +This directory will contain a directory with the sources of your chosen language, +named *{LANG}*, and also *doc-base* folder, which is home to some helpful tools. +The "en" language will always be present, as explained below. + +The documentation source is stored under "en". To only edit the source files, and +not a translation, use: ``` -svn checkout https://svn.php.net/repository/phpdoc/modules/doc-{LANG} phpdoc +svn checkout https://svn.php.net/repository/phpdoc/modules/doc-en phpdoc-en ``` -This command will create a directory named phpdoc (the name can be anything you wish). -This directory will contain a folder with the sources of your chosen language -(named *{LANG}*) and a *doc-base* folder, which is home to some helpful tools. +The "modules" directory used by these examples defines a set of SVN external definitions +that are configured to checkout multiple source directories. For example: + +- *doc-en*: checks out "en" and "doc-base" +- *doc-fr*: checks out "en", "fr", and "doc-base" +- *doc-all*: checks out all languages (there are a lot!) along with "en" and "doc-base" + +For example, to translate the manual into French, use "doc-fr" instead of "doc-en": + +``` +svn checkout https://svn.php.net/repository/phpdoc/modules/doc-fr phpdoc-fr +``` -When checking-out manual sources, you can also supply *all* as *{LANG}* making your -URL https://svn.php.net/repository/phpdoc/modules/doc-all`. This is kind of "magical" module, -which fetches every single language version of the manual, as well as doc-base folder -into your phpdoc dir. +For additional information about language codes and available translations, see http://doc.php.net/revcheck.php`. ## Files structure **Note for translators:** if any of the source files don't exist in your translation, the English content will be used