From f0dee8c4eb9148e296b3da8228ba035c9361e3cb Mon Sep 17 00:00:00 2001 From: Andreas Heigl Date: Thu, 15 Jun 2017 08:37:55 +0200 Subject: [PATCH 01/12] Renames README to README.md and adapts it This was made to reflect the steps necessary to get the whole thing up and running using git and not svn anymore --- README | 126 ------------------------------------------------ README.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+), 126 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index a2e4102d..00000000 --- a/README +++ /dev/null @@ -1,126 +0,0 @@ ---------------------------------------------------------------------------- -READ THIS FIRST ---------------------------------------------------------------------------- - This directory contains source files and a setup for converting - PHP's XML documentation into presentation formats like HTML and - RTF. You should not have to bother with this unless you are - writing documentation yourself, or if you simply are curious - about how the XML stuff works. - - If you just want to read the documentation, look at: - http://www.php.net/docs.php - ---------------------------------------------------------------------------- -HOW TO WRITE PHPDOC FILES ---------------------------------------------------------------------------- - If you are interested in information about how to - set up the tools needed, how to work with SVN and - DocBook on Linux or Windows, or what conventions you - should follow when writing phpdoc files, please refer - to the PHP Documentation HOWTO. - - You can read the HOWTO online at: - http://doc.php.net/tutorial/ - - If you are already working with the phpdoc module, - then you can find its XML source in the howto directory - of the module, and build it yourself with: - - phd -d .manual.xml - - However, PhD is a separate project which can be read about here: - - http://wiki.php.net/doc/phd - ---------------------------------------------------------------------------- -QUICK REFERENCE ---------------------------------------------------------------------------- - [[source checkout]] - - a) Check out the source - - svn checkout http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc - - Change 'doc-en' if you would like to check out a different language. - The 'modules' directory contains 'svn externals' references, so the - above actually checks out: - - svn checkout http://svn.php.net/repository/phpdoc/en/trunk phpdoc/en - svn checkout http://svn.php.net/repository/phpdoc/doc-base/trunk phpdoc/doc-base - - Where en/ is contains the DocBook source files, and doc-base/ contains tools - and resources used in all languages. - - [[edits]] - - a) Make the change. Use spaces not tabs. Be sure to carefully - watch your whitespace! - - b) Look at your unified diff, make sure it looks right and that - whitespace changes aren't mixed in: - - svn diff path/to/file.xml - - c) Make sure no errors are present, so at the command line in your - phpdoc source directory run: - - php doc-base/configure.php - - Always 'php configure.php' before commit! - - d) Commit your changes - - svn commit path/to/file.xml - - Read the HOWTO for more information. After reading the HOWTO, - email the phpdoc mailing list (phpdoc@lists.php.net) with questions - and concerns. - - [[new functions]] - - a) Copy an existing xml file or use a skeleton from the HOWTO. - Rename and place it into the appropriate directory. - - b) Edit. Be sure no leftover text exists. No tabs either. - - c) Now test locally before commit by first running - (php configure.php) - - d) svn add path/to/yourfile.xml - - e) svn commit path/to/yourfile.xml - - Note that the version numbers are taken care of elsewhere (don't worry - about them) - - [[some popular tags and entities]] - - filenames - constants - variables - a function's parameter/argument - functions, this links to function pages or bolds if - already on the function's page. it also adds (). - - teletype/mono-space font - italics - see HOWTO, includes many other tags. - internal manual links - variables - - external links via global.ent - mmm cookies - - types, this links to the given types manual - page: object -> php.net/types.object - - - &return.success; see: language-snippets.ent - &true; TRUE - &false; FALSE - &php.ini; php.ini - - Be sure to check out globals.ent and language-snippets.ent for - more information for entities and urls. - ---------------------------------------------------------------------------- diff --git a/README.md b/README.md new file mode 100644 index 00000000..0611b062 --- /dev/null +++ b/README.md @@ -0,0 +1,142 @@ +# Read Me + +## Read this first + +This directory contains source files and a setup for converting +PHP's XML documentation into presentation formats like HTML and +RTF. You should not have to bother with this unless you are +writing documentation yourself, or if you simply are curious +about how the XML stuff works. + +If you just want to read the documentation, look at: http://www.php.net/docs.php + +## How to write PHPDoc files + +If you are interested in information about how to +set up the tools needed, how to work with Git and +DocBook on Linux or Windows, or what conventions you +should follow when writing phpdoc files, please refer +to the PHP Documentation HOWTO. + +You can read the HOWTO online at http://doc.php.net/tutorial/ + +If you are already working with the phpdoc module, +then you can find its XML source in the howto directory +of the module, and build it yourself with: + +```bash +phd -d .manual.xml +``` + +However, PhD is a separate project which can be read about here: http://wiki.php.net/doc/phd + +## Quick Reference + +### Source checkout + +a. Fork the repository of the language you want to contribute to on [GitHub](https://github.com/phpdoctest) +b. Check out the source + + ```bash + git checkout git://github.com:[your github-username]/[language you want to contribute to].git + git remote add upstream https://github.com/phpdoctest/[language you want to contribute to].git + ``` + +c. Check out the doc-base repository with the different tools + + ```bash + git checkout https://github.com/phpdoctest/doc-base.git + ``` + +That will leave you with a folder ```[language you want to contribute to]``` +which contains the source-files for the documentation and a folder ```doc-base``` +that contains the different tools and resources used in all languages. + +### Edits + +a. Bring everything up to date and create a new branch + + ``` + cd [language you want to contribute to] + git fetch upstream + git checkout -b [branchname] upstream/master + ``` + +b. Make the change. Use spaces not tabs. Be sure to carefully watch your whitespace! +c. Look at your unified diff, make sure it looks right and that whitespace changes aren't mixed in: + + ```bash + git diff path/to/file.xml + ``` + +d. Make sure no errors are present, so at the command line in your phpdoc source directory run: + + ```bash + cd .. + php doc-base/configure.php + ``` + + Always ```php configure.php``` before commit! + +e. Commit your changes + + ``` + git add path/to/file.xml + git commit + git push origin branchname + ``` + +f. Open a PullRequest on GitHub for your changes to be merged directly into the main repository. + + +Read the HOWTO for more information. After reading the HOWTO, email the phpdoc +mailing list (phpdoc@lists.php.net) with questions and concerns. + +### new functions + + a) Copy an existing xml file or use a skeleton from the HOWTO. + Rename and place it into the appropriate directory. + + b) Edit. Be sure no leftover text exists. No tabs either. + + c) Now test locally before commit by first running + (php configure.php) + + d) git add add path/to/yourfile.xml + + e) git commit + + Note that the version numbers are taken care of elsewhere (don't worry + about them) + +### some popular tags and entities + + filenames + constants + variables + a function's parameter/argument + functions, this links to function pages or bolds if + already on the function's page. it also adds (). + + teletype/mono-space font + italics + see HOWTO, includes many other tags. + internal manual links + variables + + external links via global.ent + mmm cookies + + types, this links to the given types manual + page: object -> php.net/types.object + + + &return.success; see: language-snippets.ent + &true; TRUE + &false; FALSE + &php.ini; php.ini + + Be sure to check out globals.ent and language-snippets.ent for + more information for entities and urls. + +--------------------------------------------------------------------------- From 55874da981267e2b1dc5df09af8ce76260799afd Mon Sep 17 00:00:00 2001 From: Andreas Heigl Date: Mon, 14 Aug 2017 22:23:58 +0200 Subject: [PATCH 02/12] Adapts scripts to git --- TODO-GitTransfer | 0 configure.php | 27 ++++++++--------- scripts/revcheck.php | 61 +++++++++++++++++++++++++++++++++------ scripts/reviewedcheck.php | 9 +++--- 4 files changed, 71 insertions(+), 26 deletions(-) create mode 100644 TODO-GitTransfer diff --git a/TODO-GitTransfer b/TODO-GitTransfer new file mode 100644 index 00000000..e69de29b diff --git a/configure.php b/configure.php index 845ffcfa..a746070e 100755 --- a/configure.php +++ b/configure.php @@ -19,7 +19,7 @@ | Hannes Magnusson | | Gwynne Raskind | +----------------------------------------------------------------------+ - + $Id$ */ @@ -31,7 +31,7 @@ function usage() // {{{ { global $acd; - + echo <<) [{$acd['PARTIAL']}] - --disable-broken-file-listing Do not ignore translated files in + --disable-broken-file-listing Do not ignore translated files in broken-files.txt --redirect-stderr-to-stdout Redirect STDERR to STDOUT. Use STDOUT as the standard output for XML errors [{$acd['STDERR_TO_STDOUT']}] @@ -97,7 +97,7 @@ function is_windows() { function checking($for) // {{{ { global $ac; - + if ($ac['quiet'] != 'yes') { echo "Checking {$for}... "; flush(); @@ -107,7 +107,7 @@ function checking($for) // {{{ function checkerror($msg) // {{{ { global $ac; - + if ($ac['quiet'] != 'yes') { echo "\n"; } @@ -118,7 +118,7 @@ function checkerror($msg) // {{{ function checkvalue($v) // {{{ { global $ac; - + if ($ac['quiet'] != 'yes') { echo "{$v}\n"; } @@ -315,7 +315,7 @@ function print_xml_errors($details = true) { } else { continue; } - + $overridden_settings[] = strtoupper($o); switch ($o) { case 'h': @@ -399,7 +399,7 @@ function print_xml_errors($details = true) { case 'basedir': $ac['basedir'] = $v; break; - + case 'output': $ac['OUTPUT_FILENAME'] = $v; break; @@ -414,7 +414,7 @@ function print_xml_errors($details = true) { case 'stderr-to-stdout': $ac['STDERR_TO_STDOUT'] = $v; break; - + case '': break; @@ -485,6 +485,8 @@ function print_xml_errors($details = true) { if (file_exists("{$LANGDIR}/trunk")) { $LANGDIR .= '/trunk'; } + +echo $LANGDIR; if (!file_exists($LANGDIR) || !is_readable($LANGDIR)) { checkerror("No language directory found."); } @@ -674,7 +676,7 @@ function print_xml_errors($details = true) { echo "done.\n"; echo "Partial manual saved to {$filename}. To build it, run 'phd -d {$filename}'\n"; exit(0); -} // }}} +} // }}} $mxml = $ac["OUTPUT_FILENAME"]; if ($dom->validate()) { @@ -720,7 +722,7 @@ function print_xml_errors($details = true) { echo "\nThe document didn't validate, "; // Allow the .manual.xml file to be created, even if it is not valid. - if ($ac['FORCE_DOM_SAVE'] == 'yes') { + if ($ac['FORCE_DOM_SAVE'] == 'yes') { printf("writing %s anyway, and ", basename($ac["OUTPUT_FILENAME"])); if ($ac["SEGFAULT_SPEED"] == "yes") { $t = $dom->doctype; @@ -755,4 +757,3 @@ function print_xml_errors($details = true) { errors_are_bad(1); // Tell the shell that this script finished with an error. } ?> - diff --git a/scripts/revcheck.php b/scripts/revcheck.php index ed035506..9dadfa9b 100644 --- a/scripts/revcheck.php +++ b/scripts/revcheck.php @@ -52,7 +52,8 @@ functionality in the PHP Documentation Howto: set_time_limit(0); // A file is criticaly "outdated' if -define("ALERT_REV", 10); // translation is 10 or more revisions behind the en one +//define("ALERT_REV", 10); // translation is 10 or more revisions behind the en one +define("ALERT_REV", 60); // translation is 60 days behind the en one define("ALERT_SIZE", 3); // translation is 3 or more kB smaller than the en one define("ALERT_DATE", -30); // translation is 30 or more days older than the en one @@ -133,8 +134,12 @@ function init_files_by_maint($persons) { // Grabs the revision tag and stores credits from the file given function get_tags($file, $val = "en-rev") { - // Read the first 500 chars. The comment should be at + global $LANG, $DOCDIR; + $basefile = substr($file, strlen($LANG) + 3); + + // Read the first 500 chars. The comment should be at // the begining of the file + $fp = @fopen($file, "r") or die ("Unable to read $file."); $line = fread($fp, 500); fclose($fp); @@ -142,8 +147,10 @@ function get_tags($file, $val = "en-rev") { // Check for English SVN revision tag (. is for $ in the preg!), // Return if this was needed (it should be there) if ($val == "en-rev") { - preg_match("//", $line, $match); - return $match[1]; + // exec('cd ' . $DOCDIR . '/' . $LANG . ' && git log --pretty=format:"%h %at" ' . $basefile, $result, $output); + // return new DateTimeImmutable('@' . explode(' ', $result[0])[1]); + exec('cd ' . $DOCDIR . '/' . $LANG . ' && git log --pretty=format:"%h %at" ' . $basefile, $result, $output); + return new DateTimeImmutable('@' . explode(' ', $result[0])[1]); } // Handle credits (only if no maintainer is specified) @@ -168,12 +175,22 @@ function get_tags($file, $val = "en-rev") { $match = array(); // Check for the translations "revision tag" - preg_match ("//U", $line, $match ); + // The tag with revision number is not found so search + // for anonymous ID revision comment (comment where revision is not known) + if (count($match) == 0) { + preg_match ("''U", + $line, + $match + ); + } + // The tag with revision number is not found so search // for n/a revision comment (comment where revision is not known) if (count($match) == 0) { @@ -184,6 +201,15 @@ function get_tags($file, $val = "en-rev") { ); } + if (isset($match[1]) && $match[1] && $match[1] !== 'n/a') { + // We have a revision number of the english original and should now see to + // Get the last change date of that revision… + exec('cd ' . $DOCDIR . '/en && git log --pretty=format:"%h %at" ' . $basefile, $result, $output); + + $match[1] = new DateTimeImmutable('@' . (explode(' ', $result[0]))[1]); + + } + // Return with found revision info (number, maint, status) return $match; @@ -257,6 +283,9 @@ function get_file_status($file) { // Distribute values in separate vars for further processing list(, $this_rev, $this_maint, $this_status) = $trans_tag; + if ('n/a' === $this_rev) { + $this_rev = new DateTimeImmutable(); + } // Get English file revision $en_rev = get_tags($file); @@ -268,14 +297,21 @@ function get_file_status($file) { } else { // If we have no numeric revision, make all revision // columns hold the rev from the translated file - $rev_diff = $trans_rev = $this_rev; + $trans_rev = $this_rev; + $rev_diff = 0; $en_rev = $en_rev; } // Compute times and diffs $en_date = intval((time() - filemtime($file)) / 86400); + $en_date = (new DateTimeImmutable())->diff($en_rev)->days; $trans_date = intval((time() - filemtime($trans_file)) / 86400); + $trans_date = (new DateTimeImmutable())->diff($this_rev)->days; $date_diff = $en_date - $trans_date; + $date_diff = 0; + if ($trans_rev instanceof DateTimeInterface) { + $date_diff = $en_rev->diff($trans_rev)->days; + } // If the file is up-to-date if ($rev_diff === 0 && trim($this_status) === "ready") { @@ -868,12 +904,13 @@ function parse_translation($DOCDIR, $LANG, $MAINT) { '">' . $file["maintainer"] . ''; } + // FIXME: Is this diff necessary? // If we have a 'numeric' revision diff and it is not zero, // make a link to the SVN repository's diff script if ($file["revision"][2] != "n/a" && $file["revision"][2] !== 0) { $url = 'http://svn.php.net/viewvc/' . - preg_replace( "'^".$DOCDIR."en/'", 'phpdoc/en/trunk/', $file['full_name']) . - '?r1=' . $file['revision'][1] . '&r2=' . $file['revision'][0]; + preg_replace( "'^".$DOCDIR."en/'", 'phpdoc/en/trunk/', $file['full_name']); + // '?r1=' . $file['revision'][1] . '&r2=' . $file['revision'][0]; $url_ws = $url . SVN_OPT_NOWS; $url .= SVN_OPT; @@ -902,6 +939,12 @@ function parse_translation($DOCDIR, $LANG, $MAINT) { $display_dir = str_replace(array($DOCDIR."en/", $DOCDIR."en"), array("", '/'), dirname($file["full_name"])); $prev_diplay_dir = "$display_dir"; + if ($file['revision'][0] instanceof DateTimeInterface) { + $file['revision'][0] = $file['revision'][0]->format('c'); + } + if ($file['revision'][1] instanceof DateTimeInterface) { + $file['revision'][1] = $file['revision'][1]->format('c'); + } // Save the line for the current file (get file name shorter) $lines .= "{$file['short_name']}". " {$file['revision'][0]}" . @@ -1061,7 +1104,7 @@ function parse_translation($DOCDIR, $LANG, $MAINT) { $prev_dir = $new_dir; } - echo "$short_file" . + echo "$short_file" . "$info[0]\n"; } echo "\n

 

\n$navbar

 

\n"; diff --git a/scripts/reviewedcheck.php b/scripts/reviewedcheck.php index 454fc7ef..041c0a9a 100644 --- a/scripts/reviewedcheck.php +++ b/scripts/reviewedcheck.php @@ -14,7 +14,7 @@ | obtain it through the world-wide-web, please send a note to | | license@php.net so we can mail you a copy immediately. | +----------------------------------------------------------------------+ - | Authors: Yannick Torrès + | Authors: Yannick Torrès +----------------------------------------------------------------------+ $Id$ @@ -34,7 +34,7 @@ If you specify >, the output is an html file. - Authors: Yannick Torrès + Authors: Yannick Torrès File without tag | Files with Reviewed\'tags to No

'."\n"; @@ -240,7 +241,7 @@ function check_tag($dir, $file) { while( list($k, $v) = each($val) ) { -$url = 'http://cvs.php.net/viewvc.cgi/' . preg_replace( "'^".$path_doc."'", 'phpdoc-'.$LANG.'/', $key.$v).'?view=markup'; +$url = 'https://github.com/phpdoctest/' . $LANG . '/blob/master/' . preg_replace( "'^".$path_doc."'", '', $key.$v); echo ' From b0aefe749b61bddf903175a65bfae741e9828965 Mon Sep 17 00:00:00 2001 From: Andreas Heigl Date: Wed, 16 Aug 2017 08:10:55 +0200 Subject: [PATCH 03/12] Moves revision-matching to git MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit THis process now is slower than before as we need to change to the respective repos before executing a git-call for each file separately as the repos are not associated any more… --- scripts/revcheck.php | 96 ++++++++++++++++++++++++++------------------ 1 file changed, 57 insertions(+), 39 deletions(-) diff --git a/scripts/revcheck.php b/scripts/revcheck.php index 9dadfa9b..fce92948 100644 --- a/scripts/revcheck.php +++ b/scripts/revcheck.php @@ -53,7 +53,7 @@ functionality in the PHP Documentation Howto: // A file is criticaly "outdated' if //define("ALERT_REV", 10); // translation is 10 or more revisions behind the en one -define("ALERT_REV", 60); // translation is 60 days behind the en one +define("ALERT_REV", 5); // English original has 5 or more new revisions since the set revision define("ALERT_SIZE", 3); // translation is 3 or more kB smaller than the en one define("ALERT_DATE", -30); // translation is 30 or more days older than the en one @@ -96,10 +96,6 @@ function init_files_by_maint($persons) { $file_sizes_by_mark = $files_by_mark = init_revisions(); -// Option for the link to svn.php.net: -define('SVN_OPT', '&view=patch'); -define('SVN_OPT_NOWS', ''); - // Initializing variables from parameters $LANG = $argv[1]; $MAINT = ""; @@ -131,6 +127,18 @@ function init_files_by_maint($persons) { // Functions to get revision info and credits from a file // ========================================================================= +function get_original_info($file, $hash) +{ + global $DOCDIR; + + exec('cd ' . $DOCDIR . '/en/ && git log ' . $hash . '^.. --pretty=format:"%h %at" -- ' . $file, $result, $output); + if ($output || ! $result) { + return [new DateTimeImmutable(), 0]; + } + return [new DateTimeImmutable('@' . explode(' ', $result[0])[1]), count($result) - 1]; + +} + // Grabs the revision tag and stores credits from the file given function get_tags($file, $val = "en-rev") { @@ -147,9 +155,7 @@ function get_tags($file, $val = "en-rev") { // Check for English SVN revision tag (. is for $ in the preg!), // Return if this was needed (it should be there) if ($val == "en-rev") { - // exec('cd ' . $DOCDIR . '/' . $LANG . ' && git log --pretty=format:"%h %at" ' . $basefile, $result, $output); - // return new DateTimeImmutable('@' . explode(' ', $result[0])[1]); - exec('cd ' . $DOCDIR . '/' . $LANG . ' && git log --pretty=format:"%h %at" ' . $basefile, $result, $output); + exec('cd ' . $DOCDIR . '/' . $LANG . ' && git log -1 --pretty=format:"%h %at" ' . $basefile, $result, $output); return new DateTimeImmutable('@' . explode(' ', $result[0])[1]); } @@ -166,6 +172,9 @@ function get_tags($file, $val = "en-rev") { // Store all elements foreach ($credits as $num => $credit) { + if (! isset($files_by_maint[trim($credit)][REV_CREDIT])) { + $files_by_maint[trim($credit)][REV_CREDIT] = 0; + } $files_by_maint[trim($credit)][REV_CREDIT]++; } } @@ -184,7 +193,8 @@ function get_tags($file, $val = "en-rev") { // The tag with revision number is not found so search // for anonymous ID revision comment (comment where revision is not known) if (count($match) == 0) { - preg_match ("''U", $line, $match @@ -194,23 +204,29 @@ function get_tags($file, $val = "en-rev") { // The tag with revision number is not found so search // for n/a revision comment (comment where revision is not known) if (count($match) == 0) { - preg_match ("''U", - $line, - $match + $line, + $match ); } + $match[4] = new DateTimeImmutable(); + $match[5] = 0; if (isset($match[1]) && $match[1] && $match[1] !== 'n/a') { // We have a revision number of the english original and should now see to // Get the last change date of that revision… - exec('cd ' . $DOCDIR . '/en && git log --pretty=format:"%h %at" ' . $basefile, $result, $output); - - $match[1] = new DateTimeImmutable('@' . (explode(' ', $result[0]))[1]); + $info = get_original_info($basefile, $match[1]); + $match[4] = $info[0]; + $match[5] = $info[1]; } - // Return with found revision info (number, maint, status) + //exec('cd ' . $DOCDIR . '/' . $LANG . ' && git log -1 --pretty=format:"%h %at" ' . $basefile, $result, $output); + $match[1] = get_tags($file, 'en-rev'); + + // Return with found revision info (number, maint, status) return $match; } // get_tags() function end @@ -281,36 +297,30 @@ function get_file_status($file) { } // Distribute values in separate vars for further processing - list(, $this_rev, $this_maint, $this_status) = $trans_tag; + list(, $this_rev, $this_maint, $this_status, $en_last_date, $rev_diff) = $trans_tag; - if ('n/a' === $this_rev) { - $this_rev = new DateTimeImmutable(); - } - // Get English file revision - $en_rev = get_tags($file); + if ('n/a' === $this_rev) { + $this_rev = new DateTimeImmutable(); + } - // If we have a numeric revision number (not n/a), compute rev. diff if (is_numeric($this_rev)) { - $rev_diff = intval($en_rev) - intval($this_rev); $trans_rev = $this_rev; - $en_rev = $en_rev; + $en_rev = $this_rev; } else { // If we have no numeric revision, make all revision // columns hold the rev from the translated file $trans_rev = $this_rev; - $rev_diff = 0; - $en_rev = $en_rev; + $en_rev = 0; } // Compute times and diffs - $en_date = intval((time() - filemtime($file)) / 86400); - $en_date = (new DateTimeImmutable())->diff($en_rev)->days; + $en_date = (new DateTimeImmutable())->diff($en_last_date)->days; $trans_date = intval((time() - filemtime($trans_file)) / 86400); - $trans_date = (new DateTimeImmutable())->diff($this_rev)->days; + // $trans_date = (new DateTimeImmutable())->diff($this_rev)->days; $date_diff = $en_date - $trans_date; $date_diff = 0; if ($trans_rev instanceof DateTimeInterface) { - $date_diff = $en_rev->diff($trans_rev)->days; + $date_diff = $en_last_date->diff($trans_rev)->days; } // If the file is up-to-date @@ -330,6 +340,9 @@ function get_file_status($file) { // Store files by status, and by maintainer too $files_by_mark[$status_mark]++; + if (! isset($files_by_maint[$this_maint][$status_mark])) { + $files_by_maint[$this_maint][$status_mark] = 0; + } $files_by_maint[$this_maint][$status_mark]++; $file_sizes_by_mark[$status_mark] += $en_size; @@ -340,7 +353,7 @@ function get_file_status($file) { return array( "full_name" => $file, "short_name" => basename($trans_file), - "revision" => array($en_rev, $trans_rev, $rev_diff), + "revision" => array($en_rev, $rev_diff, $trans_rev), "size" => array($en_size, $trans_size, $size_diff), "date" => array($en_date, $trans_date, $date_diff), "maintainer" => $this_maint, @@ -369,10 +382,11 @@ function get_dir_status($dir) { // Walk through all names in the directory while ($file = @readdir($handle)) { - if ( (!is_dir($dir.'/' .$file) && !in_array(substr($file, -3), array('xml','ent')) && substr($file, -13) != 'PHPEditBackup' ) || strpos($file, 'entities.') === 0 + || strpos($file, '.git') === 0 + || strpos($file, '.idea') === 0 || $dir == $DOCDIR.'en/chmonly/' || $dir == $DOCDIR.'en/internals/' || $dir == $DOCDIR.'en/internals2/' || $file == 'contributors.ent' || $file == 'contributors.xml' || ($dir == $DOCDIR.'en/appendices/' && ($file == 'reserved.constants.xml' || $file == 'extensions.xml')) @@ -908,14 +922,18 @@ function parse_translation($DOCDIR, $LANG, $MAINT) { // If we have a 'numeric' revision diff and it is not zero, // make a link to the SVN repository's diff script if ($file["revision"][2] != "n/a" && $file["revision"][2] !== 0) { - $url = 'http://svn.php.net/viewvc/' . - preg_replace( "'^".$DOCDIR."en/'", 'phpdoc/en/trunk/', $file['full_name']); - // '?r1=' . $file['revision'][1] . '&r2=' . $file['revision'][0]; - $url_ws = $url . SVN_OPT_NOWS; - $url .= SVN_OPT; + $history_url = sprintf( + 'https://github.com/phpdoctest/en/commits/master/%1$s', + $file['full_name'] + ); + + $url = sprintf( + 'https://github.com/phpdoctest/en/blob/master/%1$s', + $file['full_name'] + ); $file['short_name'] = ''. $file["short_name"] . ' '. - '[NoWS]'; + '[History]'; } // Guess the new directory from the full name of the file From 8124ef118fe5f591e38b1797601dea7cbcf00073 Mon Sep 17 00:00:00 2001 From: Sobak Date: Sat, 18 Nov 2017 09:49:02 +0100 Subject: [PATCH 04/12] Fix indented code blocks in Markdownified README --- README.md | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 0611b062..062a98eb 100644 --- a/README.md +++ b/README.md @@ -37,16 +37,16 @@ However, PhD is a separate project which can be read about here: http://wiki.php a. Fork the repository of the language you want to contribute to on [GitHub](https://github.com/phpdoctest) b. Check out the source - ```bash - git checkout git://github.com:[your github-username]/[language you want to contribute to].git - git remote add upstream https://github.com/phpdoctest/[language you want to contribute to].git - ``` +```bash +git checkout git://github.com:[your github-username]/[language you want to contribute to].git +git remote add upstream https://github.com/phpdoctest/[language you want to contribute to].git +``` c. Check out the doc-base repository with the different tools - ```bash - git checkout https://github.com/phpdoctest/doc-base.git - ``` +```bash +git checkout https://github.com/phpdoctest/doc-base.git +``` That will leave you with a folder ```[language you want to contribute to]``` which contains the source-files for the documentation and a folder ```doc-base``` @@ -56,35 +56,35 @@ that contains the different tools and resources used in all languages. a. Bring everything up to date and create a new branch - ``` - cd [language you want to contribute to] - git fetch upstream - git checkout -b [branchname] upstream/master - ``` +``` +cd [language you want to contribute to] +git fetch upstream +git checkout -b [branchname] upstream/master +``` b. Make the change. Use spaces not tabs. Be sure to carefully watch your whitespace! c. Look at your unified diff, make sure it looks right and that whitespace changes aren't mixed in: - ```bash - git diff path/to/file.xml - ``` +```bash +git diff path/to/file.xml +``` d. Make sure no errors are present, so at the command line in your phpdoc source directory run: - ```bash - cd .. - php doc-base/configure.php - ``` +```bash +cd .. +php doc-base/configure.php +``` Always ```php configure.php``` before commit! e. Commit your changes - ``` - git add path/to/file.xml - git commit - git push origin branchname - ``` +``` +git add path/to/file.xml +git commit +git push origin branchname +``` f. Open a PullRequest on GitHub for your changes to be merged directly into the main repository. From b038b35e47c9a60564cf5cb8e9f58a90330b8ff4 Mon Sep 17 00:00:00 2001 From: Sobak Date: Sat, 25 Nov 2017 01:47:10 +0100 Subject: [PATCH 05/12] Alias setup script to easier name --- scripts/setup.php | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 scripts/setup.php diff --git a/scripts/setup.php b/scripts/setup.php new file mode 100644 index 00000000..1c96c413 --- /dev/null +++ b/scripts/setup.php @@ -0,0 +1,3 @@ + Date: Sat, 25 Nov 2017 01:57:47 +0100 Subject: [PATCH 06/12] Add languages.list file --- languages.info | 13 +++++++++++++ languages.list | 5 +++++ scripts/create-phpdoc-setup.php | 5 +++++ 3 files changed, 23 insertions(+) create mode 100644 languages.info create mode 100644 languages.list diff --git a/languages.info b/languages.info new file mode 100644 index 00000000..4c4e45e7 --- /dev/null +++ b/languages.info @@ -0,0 +1,13 @@ +The languages.list is used in place of old svn:externals solution to allow +tools discover all the languages (including en) of the PHP Manual. It means +that it is crucial to add every new translation there. For the record, empty +lines are ignored, as well as anything starting with "#" is treated as a +comment. + +Sample PHP implementation: + +function get_langugages() { + return array_filter(file('/path/to/languages.list', FILE_IGNORE_NEW_LINES), function ($line) { + return $line !== '' && $line[0] !== '#'; + }); +} diff --git a/languages.list b/languages.list new file mode 100644 index 00000000..c42773e0 --- /dev/null +++ b/languages.list @@ -0,0 +1,5 @@ +# For more informations please read languages.info +# Keep 'em sorted! +# @todo: update list once migration is done! +de +en diff --git a/scripts/create-phpdoc-setup.php b/scripts/create-phpdoc-setup.php index 89c660d7..afe1367a 100644 --- a/scripts/create-phpdoc-setup.php +++ b/scripts/create-phpdoc-setup.php @@ -290,3 +290,8 @@ function echo_line($line = '', $newline = TRUE) { echo PHP_EOL; } } +function get_langugages() { + return array_filter(file('../languages.list', FILE_IGNORE_NEW_LINES), function ($line) { + return $line !== '' && $line[0] !== '#'; + }); +} From 0dbbaaf88ec47babf86f7170627dbc4ebf2b929b Mon Sep 17 00:00:00 2001 From: Sobak Date: Sat, 25 Nov 2017 07:09:28 +0100 Subject: [PATCH 07/12] Initial (but working) rewrite to Git --- scripts/create-phpdoc-setup.php | 102 ++++++++++++++++---------------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/scripts/create-phpdoc-setup.php b/scripts/create-phpdoc-setup.php index afe1367a..7ba060d0 100644 --- a/scripts/create-phpdoc-setup.php +++ b/scripts/create-phpdoc-setup.php @@ -1,17 +1,14 @@ 'Help : This help', 't' => 'TEST Mode: Test mode. Writes nothing. Displays your configs', 'l' => 'Language : Country code, typically two letters. Default: en', - 'b' => 'SVN dir : Full path to the SVN base dir, where PHP will be checked out', - 's' => 'SVN path: Full path to the SVN binary', + 'b' => 'Git dir : Full path to the Git base dir, where PHP will be checked out', + 's' => 'Git path: Full path to the Git binary', 'd' => 'PhD path: PhD renders the manual, you probably do not have it installed', 'r' => 'PEAR path: Full path to the pear command', 'p' => 'PHP path: Full path to the PHP binary', - 'u' => 'SVN Up : Update the existing SVN checkout', + 'u' => 'Git pull: Update the existing Git repositories', ); echo_line(); - echo_line('This script checks out PHP from SVN, and installs PhD.'); + echo_line('This script clones PHP Manual from Git, and installs PhD.'); echo_line('The following options are available. All but -b are optional.'); echo_line(); - echo_line('Example: php ' . $_SERVER['SCRIPT_NAME'] . ' -b /my/svn -l en'); - echo_line('Creates: /my/svn/doc-en/ with full php documentation checkout'); + echo_line('Example: php ' . $_SERVER['SCRIPT_NAME'] . ' -b /my/repos -l en'); + echo_line('Creates: /my/repos/en/ with full php documentation checkout'); echo_line(); foreach ($descriptions as $config_n => $config_v) { echo_line(' -' . $config_n . ' : ' . $config_v); @@ -235,12 +235,12 @@ function do_getopts() { $options = getopt('b:l:p:r:d:s:uht'); $defaults = $configs = array( 'h' => '', // Show usage/help information - 'b' => '', // Base directory for the SVN Checkout + 'b' => '', // Base directory for the Git Checkout 'l' => 'en', // Language (en, or lang code for translation) 'p' => '', // PHP binary Path 'r' => '', // PEAR binary Path 'd' => '', // PHD binary Path - 's' => '', // SVN binary Path + 's' => '', // Git binary Path 'u' => '', // Update the checkout, instead of checkout 't' => '', // Test. Outputs your configuration. ); @@ -256,29 +256,29 @@ function do_getopts() { } } $configs = array( - 'BASEDIR_SVN' => $configs['b'], + 'BASEDIR_GIT' => $configs['b'], 'LANG_CODE' => $configs['l'], 'PATH_PHP' => $configs['p'], 'PATH_PEAR' => $configs['r'], 'PATH_PHD' => $configs['d'], - 'PATH_SVN' => $configs['s'], + 'PATH_GIT' => $configs['s'], 'UPDATE_CO' => $configs['u'], 'HELP' => $configs['h'], 'TEST' => $configs['t'], ); - if (!empty($configs['BASEDIR_SVN'])) { - $configs['DIR_SVN'] = $configs['BASEDIR_SVN'] . '/doc-' . $configs['LANG_CODE']; + if (!empty($configs['BASEDIR_GIT'])) { + $configs['DIR_GIT'] = $configs['BASEDIR_GIT']; } return $configs; } function is_phpdoc_checkout($configs) { - if (empty($configs['DIR_SVN'])) { + if (empty($configs['DIR_GIT'])) { echo_line('Warning: Configuration is not set properly while testing the checkout. Massive fail!'); exit; } // TODO: Improve this check - if (file_exists($configs['DIR_SVN'] . '/en/reference/apc/book.xml') && file_exists($configs['DIR_SVN'] . '/doc-base/configure.php')) { + if (file_exists($configs['DIR_GIT'] . '/en/reference/apc/book.xml')) { return true; } else { return false; From e75dd7c7a14d18c0c956056b46e791fc18fdab56 Mon Sep 17 00:00:00 2001 From: Sobak Date: Sat, 25 Nov 2017 07:17:13 +0100 Subject: [PATCH 08/12] Eliminate now redundant variable --- scripts/create-phpdoc-setup.php | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/scripts/create-phpdoc-setup.php b/scripts/create-phpdoc-setup.php index 7ba060d0..343fc50f 100644 --- a/scripts/create-phpdoc-setup.php +++ b/scripts/create-phpdoc-setup.php @@ -112,10 +112,10 @@ exit; } } else { - echo_line('Running: Checking out the docs from Git to here: ' . $configs['DIR_GIT']); + echo_line('Running: Checking out the docs from Git to here: ' . $configs['BASEDIR_GIT']); foreach ($languages as $language) { // @todo: update URL when migration is done - shell_exec("git clone git@github.com:phpdoctest/{$language}.git {$configs['DIR_GIT']}/{$language}"); + shell_exec("git clone git@github.com:phpdoctest/{$language}.git {$configs['BASEDIR_GIT']}/{$language}"); } echo_line('Checking: Seeing if the Git checkout was a success: ', FALSE); @@ -128,7 +128,7 @@ } } -chdir($configs['DIR_GIT']); +chdir($configs['BASEDIR_GIT']); echo_line('Status: Current working directory now: '. getcwd()); // FIXME: Capture stdout/stderr on error @@ -166,12 +166,12 @@ echo_line(); echo_line('INFO: Done. You now have the PHP Documentation checked out:'); -echo_line('-- PHP Documentation Git path: '. $configs['DIR_GIT']); +echo_line('-- PHP Documentation Git path: '. $configs['BASEDIR_GIT']); echo_line('-- PhD Installed: '. (empty($configs['PATH_PHD']) ? 'no' : $configs['PATH_PHD'])); echo_line(); echo_line('INFO: Now, some things you might want to do:'); $subdirectory = $configs['LANG_CODE'] == 'all' ? 'en' : $configs['LANG_CODE']; -echo_line('-- Go there : cd ' . rtrim($configs['DIR_GIT'], '/') . '/' . $subdirectory); +echo_line('-- Go there : cd ' . rtrim($configs['BASEDIR_GIT'], '/') . '/' . $subdirectory); echo_line('-- Validate XML : php ../doc-base/configure.php'); echo_line('-- Render XHTML : phd --docbook doc-base/.manual.xml --package PHP --format xhtml'); echo_line('-- View it : open output/php-chunked-xhtml/index.html &'); @@ -266,19 +266,16 @@ function do_getopts() { 'HELP' => $configs['h'], 'TEST' => $configs['t'], ); - - if (!empty($configs['BASEDIR_GIT'])) { - $configs['DIR_GIT'] = $configs['BASEDIR_GIT']; - } + return $configs; } function is_phpdoc_checkout($configs) { - if (empty($configs['DIR_GIT'])) { + if (empty($configs['BASEDIR_GIT'])) { echo_line('Warning: Configuration is not set properly while testing the checkout. Massive fail!'); exit; } // TODO: Improve this check - if (file_exists($configs['DIR_GIT'] . '/en/reference/apc/book.xml')) { + if (file_exists($configs['BASEDIR_GIT'] . '/en/reference/apc/book.xml')) { return true; } else { return false; From fcab4c53ee936e6671070b3c2e58a3ba197c894b Mon Sep 17 00:00:00 2001 From: Sobak Date: Sat, 25 Nov 2017 07:21:38 +0100 Subject: [PATCH 09/12] Normalize path --- scripts/create-phpdoc-setup.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/create-phpdoc-setup.php b/scripts/create-phpdoc-setup.php index 343fc50f..985b69df 100644 --- a/scripts/create-phpdoc-setup.php +++ b/scripts/create-phpdoc-setup.php @@ -256,7 +256,7 @@ function do_getopts() { } } $configs = array( - 'BASEDIR_GIT' => $configs['b'], + 'BASEDIR_GIT' => rtrim($configs['b'], '/'), 'LANG_CODE' => $configs['l'], 'PATH_PHP' => $configs['p'], 'PATH_PEAR' => $configs['r'], From 6cf084e1ad510c1139fcc7b6fbd4fbda31da1511 Mon Sep 17 00:00:00 2001 From: Sobak Date: Sat, 25 Nov 2017 08:08:37 +0100 Subject: [PATCH 10/12] Modify checkout logic as per new requirements --- scripts/create-phpdoc-setup.php | 57 +++++++++++++++++---------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/scripts/create-phpdoc-setup.php b/scripts/create-phpdoc-setup.php index 985b69df..b5ab59bd 100644 --- a/scripts/create-phpdoc-setup.php +++ b/scripts/create-phpdoc-setup.php @@ -99,32 +99,30 @@ } // Required: git clone -// Checking: Is this already checked out? // Note: If already checked out, use -u to update instead. -echo_line('Checking: Seeing if you already checked out the docs here.'); -if (is_phpdoc_checkout($configs)) { - if ($configs['UPDATE_CO']) { - echo_line('Status: The checkout already exists, but -u was used so I am updating instead.'); - $command = 'svn up ' . $configs['DIR_SVN']; - shell_exec($command); +foreach ($languages as $language) { + if (is_phpdoc_checkout($configs, $language)) { + if ($configs['UPDATE_CO']) { + echo_line('Status: The checkout for ' . $language . ' already exists, but -u was used so I am updating instead.'); + chdir($configs['BASEDIR_GIT'] . '/' . $language); + shell_exec('git pull'); + } else { + echo_line('Warning: ' . $language . ' already checked out. Pass in -u to update instead.'); + } } else { - echo_line('Warning: This is already checked out. Pass in -u to update instead.'); - exit; - } -} else { - echo_line('Running: Checking out the docs from Git to here: ' . $configs['BASEDIR_GIT']); - foreach ($languages as $language) { - // @todo: update URL when migration is done + echo_line('Running: Checking out ' . $language . ' docs from Git to here: ' . $configs['BASEDIR_GIT']); + + // @todo: update URL once migration is done shell_exec("git clone git@github.com:phpdoctest/{$language}.git {$configs['BASEDIR_GIT']}/{$language}"); - } - echo_line('Checking: Seeing if the Git checkout was a success: ', FALSE); - if (is_phpdoc_checkout($configs)) { - echo_line('Yes.'); - } else { - // Hmm.... - echo_line('No. I am extremely confused, so will exit.'); - exit; + echo_line('Checking: Seeing if the Git checkout was a success: ', FALSE); + if (is_phpdoc_checkout($configs, $language)) { + echo_line('Yes.'); + } else { + // Hmm.... + echo_line('No. I am extremely confused, so will exit.'); + exit; + } } } @@ -269,17 +267,22 @@ function do_getopts() { return $configs; } -function is_phpdoc_checkout($configs) { +function is_phpdoc_checkout($configs, $language) { if (empty($configs['BASEDIR_GIT'])) { echo_line('Warning: Configuration is not set properly while testing the checkout. Massive fail!'); exit; } - // TODO: Improve this check - if (file_exists($configs['BASEDIR_GIT'] . '/en/reference/apc/book.xml')) { - return true; - } else { + + $directory = $configs['BASEDIR_GIT'] . '/' . $language; + + if (!is_dir($directory)) { return false; } + + chdir($directory); + exec('git status', $output, $return_code); + + return $return_code === 0; } function echo_line($line = '', $newline = TRUE) { echo $line; From a30f04fe5bf561b24136edcf7e59da8c65722bbd Mon Sep 17 00:00:00 2001 From: Sobak Date: Sat, 25 Nov 2017 08:14:38 +0100 Subject: [PATCH 11/12] Minor cleanup --- scripts/create-phpdoc-setup.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/scripts/create-phpdoc-setup.php b/scripts/create-phpdoc-setup.php index b5ab59bd..33a9c9dd 100644 --- a/scripts/create-phpdoc-setup.php +++ b/scripts/create-phpdoc-setup.php @@ -104,7 +104,7 @@ if (is_phpdoc_checkout($configs, $language)) { if ($configs['UPDATE_CO']) { echo_line('Status: The checkout for ' . $language . ' already exists, but -u was used so I am updating instead.'); - chdir($configs['BASEDIR_GIT'] . '/' . $language); + chdir($configs['BASEDIR_GIT'] . $language); shell_exec('git pull'); } else { echo_line('Warning: ' . $language . ' already checked out. Pass in -u to update instead.'); @@ -113,7 +113,7 @@ echo_line('Running: Checking out ' . $language . ' docs from Git to here: ' . $configs['BASEDIR_GIT']); // @todo: update URL once migration is done - shell_exec("git clone git@github.com:phpdoctest/{$language}.git {$configs['BASEDIR_GIT']}/{$language}"); + shell_exec("git clone git@github.com:phpdoctest/{$language}.git {$configs['BASEDIR_GIT']}{$language}"); echo_line('Checking: Seeing if the Git checkout was a success: ', FALSE); if (is_phpdoc_checkout($configs, $language)) { @@ -169,7 +169,7 @@ echo_line(); echo_line('INFO: Now, some things you might want to do:'); $subdirectory = $configs['LANG_CODE'] == 'all' ? 'en' : $configs['LANG_CODE']; -echo_line('-- Go there : cd ' . rtrim($configs['BASEDIR_GIT'], '/') . '/' . $subdirectory); +echo_line('-- Go there : cd ' . $configs['BASEDIR_GIT'] . $subdirectory); echo_line('-- Validate XML : php ../doc-base/configure.php'); echo_line('-- Render XHTML : phd --docbook doc-base/.manual.xml --package PHP --format xhtml'); echo_line('-- View it : open output/php-chunked-xhtml/index.html &'); @@ -254,7 +254,7 @@ function do_getopts() { } } $configs = array( - 'BASEDIR_GIT' => rtrim($configs['b'], '/'), + 'BASEDIR_GIT' => rtrim($configs['b'], '/') . '/', 'LANG_CODE' => $configs['l'], 'PATH_PHP' => $configs['p'], 'PATH_PEAR' => $configs['r'], @@ -273,7 +273,7 @@ function is_phpdoc_checkout($configs, $language) { exit; } - $directory = $configs['BASEDIR_GIT'] . '/' . $language; + $directory = $configs['BASEDIR_GIT'] . $language; if (!is_dir($directory)) { return false; From ad26ea0359f16168d80c6400d5ae368e4073811d Mon Sep 17 00:00:00 2001 From: Sobak Date: Sat, 25 Nov 2017 22:16:03 +0100 Subject: [PATCH 12/12] Support Windows --- scripts/create-phpdoc-setup.php | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/scripts/create-phpdoc-setup.php b/scripts/create-phpdoc-setup.php index 33a9c9dd..ee2b9964 100644 --- a/scripts/create-phpdoc-setup.php +++ b/scripts/create-phpdoc-setup.php @@ -10,7 +10,6 @@ TODO: - Find/Fix bugs that most likely exist - - Make it work on Windows - Test in different environments - Increase intelligence of several checks - Add notification bar when doing something (e.g., checking out, running configure.php) @@ -196,9 +195,9 @@ function get_installed_path($program, $test_path = NULL, $version = '--version') // Now try finding it ourselves... // FIXME: will this always work? - $command = "which $program 2>&1"; + $command = DIRECTORY_SEPARATOR == '/' ? "which $program 2>&1" : "where $program"; $out = shell_exec($command); - if (false !== strpos($out, '/' . $program)) { + if (false !== strpos($out, DIRECTORY_SEPARATOR . $program)) { return trim($out); } return false;