cvs: phpdoc /htmlhelp .cvsignore README.txt TODO.txt filter_files.php local_vars.php local_vars.php.src make_chm.bat make_chm.php mirrors_ini.php
split_notes.php user_notes.php
| From: | Gabor Hojtsy | Date: | Thu, 26 Dec 2002 19:11:04 +0000 |
| Subject: | cvs: phpdoc /htmlhelp .cvsignore README.txt TODO.txt filter_files.php local_vars.php local_vars.php.src make_chm.bat make_chm.php mirrors_ini.php split_notes.php user_notes.php |
||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969350400@lists.php.net to get a copy of this message | ||
goba Thu Dec 26 14:11:04 2002 EDT
Added files:
/phpdoc/htmlhelp .cvsignore filter_files.php local_vars.php
local_vars.php.src make_chm.bat make_chm.php
mirrors_ini.php README.txt split_notes.php
TODO.txt user_notes.php
Log:
Adding the "new CHM" build system to CVS.
Here is my Christmas present to you all ;)
This also contains a short README and a not too short TODO.
Index: phpdoc/htmlhelp/.cvsignore +++ phpdoc/htmlhelp/.cvsignore html htmlout notesin notesout release local_vars.php mirrors.inc all Index: phpdoc/htmlhelp/filter_files.php +++ phpdoc/htmlhelp/filter_files.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. The filters included in this file are to refine the XSL generated HTML codes. Some filters may be converted to XSL templates, but not all. */ $counter = filterFiles(); // Filter XSL generated files through some refine filters function filterFiles() { global $HTML_SRC, $HTML_TARGET, $INDEX_FILE; // How many files were processed $counter = 0; // Try to figure out what index file to use if (file_exists("$HTML_SRC/index.html")) { $INDEX_FILE = "index.html"; } else { $INDEX_FILE = "manual.html"; } // Open the directory, and do the work on all HTML files $handle = opendir($HTML_SRC); while (false !== ($filename = readdir($handle))) { // Only process html files if (strpos($filename, ".html")) { $counter++; refineFile($filename); echo "> $counter\r"; } } closedir($handle); // Open supplemental files directory, and copy // all files to output directory $handle = opendir("./suppfiles/html/"); while (false !== ($filename = readdir($handle))) { if (!in_array($filename, array(".", ".."))) { copy("suppfiles/html/$filename", "$HTML_TARGET/$filename"); $counter++; echo "> $counter\r"; } } closedir($handle); // Copy source Help files from html dir to output dir copy("$HTML_SRC/php_manual_en.hhp", "$HTML_TARGET/php_manual_en.hhp"); copy("$HTML_SRC/php_manual_en.hhc", "$HTML_TARGET/php_manual_en.hhc"); copy("$HTML_SRC/php_manual_en.hhk", "$HTML_TARGET/php_manual_en.hhk"); return $counter; } // filterFiles() function end // Refine HTML code in XSL generated files function refineFile($filename) { global $HTML_SRC, $HTML_TARGET, $INDEX_FILE, $preNum; // The number of <pre> parts is zero (used for example copy links) $preNum = 0; // Read in the contents of the source file $content = join("", file("$HTML_SRC/$filename")); //------------------------------------------------------------------ // Find page title and format it properly preg_match('!<title>\s*(.+)</title>!Us', $content, $matched); $page_title = $matched[1]; // Replace title with simple <title> content [shorter, without tags] $content = preg_replace( '!<h(\d)[^>]*>.+</h\1>!Us', "<h1 class=\"masterheader\"><span id=\"pageTitle\">$page_title</span></h1>", $content, 1 ); //------------------------------------------------------------------ // Add divisions for skin support // Make the document invisible by default, adding a new first div $content = preg_replace( '!(<div class="(\w+)">)!Us', '<div id="pageContent" style="display:none;">\1<div id="pageHeaders">', $content, 1 ); // Put there the end of this pageContent $content = str_replace( '</body></html>', '</div></body></html>', $content ); // For headers we have several possibilities if (strpos($content, '<div class="refnamediv">') !== FALSE) { // A function page if (!strpos($content, "refsynopsisdiv")) { $content = str_replace( '</h2></div><div class="refsect1">', '</h2></div></div><div id="pageText"><div class="refsect1">', $content ); } // The COM or VARIANT classes page (which contain refsynopsisdiv) else { $content = str_replace( '<div class="refsynopsisdiv">', '</div><div id="pageText"><div class="refsynopsisdiv">', $content ); } } // Normal page, and not an index elseif ($filename != $INDEX_FILE) { $content = preg_replace( '!</h1></div>(<p>)?</div>!', '</h1></div>\\1</div></div><div id="pageText">', $content ); } // The index page else { // Delete titlepage div and // add pageHeader end and pageText start $content = str_replace( array("<div class=\"titlepage\">", "<hr></div>"), array("", "<hr>"), $content ); $content = preg_replace( '!</h1></div><div>!', '</h1></div></div><div id="pageText"><div>', $content ); } // End that pageText div before the user notes $content = str_replace( '<a name="_user_notes">', '</div><a name="_user_notes">', $content ); // If this is the index file, correct it if ($filename == $INDEX_FILE) { $content = newIndex($content); } //------------------------------------------------------------------ // Change pre sections look (examples, screen outputs, etc). $content = preg_replace_callback( '!<pre class="([^"]+)">(.+)</pre>!Us', "formatPre", $content ); //------------------------------------------------------------------ // Put <p> tags after all </ul> or </div> or </table> close tags to // enable CSS support for those paragraphs (these break a <p>) // BUT do not put a P after our special notes container $content = preg_replace('!</(ul|div|table)>!Us', '</\\1><p>', $content); $content = str_replace('<div id="pageNotes"></div><p>', '<div id="pageNotes"></div>', $content); //------------------------------------------------------------------ // Delete duplicate <p> tags from code, unneded <p></p> parts, and // <p> before <table> or <div> or </div> or </body> or <ul> $content = preg_replace('!<p>\s*<p>!Us', '<p>', $content); $content = preg_replace('!<p>\s*</p>!Us', '', $content); $content = preg_replace('!<p>\s*<(table|div|/div|/body|ul)!Us', '<\\1', $content); //------------------------------------------------------------------ // Drop out all the <div> and </div> tags left (no need to have them) //$content = preg_replace('!</?div[^>]*>!Us', '', $content); // !!! Temporary fix for XSLT output escaping problems $content = preg_replace("!&raquo; !", "» ", $content); //------------------------------------------------------------------ // Write out file to HTML output directory $fp = fopen("$HTML_TARGET/$filename", "w"); fwrite($fp, $content); fclose($fp); } // newFace() function end // Make the old index look somewhat better function newIndex ($content) { global $HTML_TARGET; // Get contents we need to build the _index.html file preg_match("!^(.+)<hr>!s", $content, $_index1); preg_match("!(</div></div><a name=\"_user_notes\">.+</html>)!s", $content, $_index2); // Write out the two components to form a complete file $fp = fopen("$HTML_TARGET/_index.html", "w"); fwrite($fp, $_index1[1] . $_index2[1]); fclose($fp); // Drop out authors list (this is on the frontpage) $content = preg_replace( '!<div id="pageText"><div>.*<hr>!Us', '<div id="pageText">', $content ); // Get TOC title from HTML code preg_match( '!<div class="toc"><p><b>(.+)</b></p>!U', $content, $match ); // Put toc title into title places $content = preg_replace( '!<title>(.+)</title>!U', "<title>$match[1]</title>", $content ); $content = preg_replace( '!<span id="pageTitle">(.+)</span>!U', "<span id=\"pageTitle\">$match[1]</span>", $content ); // Drop out small TOC title $content = preg_replace( '!<div class="toc"><p><b>(.+)</b></p>!U', '<div class="toc">', $content ); return $content; } // newIndex() function end // Change pre sections look function formatPre () { // Number of <pre> sections on this page global $preNum; // Construct clipboard copy link $preNum++; $linkwdiv = '<div class="codelink"><a href="javascript:void(0);" onclick="copyExample(\'' . $preNum . '\')">copy to clipboard</a></div><div class="examplecode">'; // Replace all hard line breaks list($pre_found) = func_get_args(); // Not a PHP example if ($pre_found[1] != 'php') { return $linkwdiv . '<code id="example_' . $preNum . '">' . pre2code(trim($pre_found[2])) . '</code></div><p>'; } // Convert entities to characters for color coding $example = str_replace( array(">", "<", "&", """), array(">", "<", "&", "\""), $pre_found[2] ); // Trim example code to get rid of extra line breaks $example = trim($example); // Start output buffer, add PHP tags if none is there ob_start(); if (!strstr($example, "<?php")) { $example = "<?php " . $example . " ?>"; $delimiter = FALSE; } else { $delimiter = TRUE; } // Get highlited source code highlight_string($example); $colored_example = ob_get_contents(); ob_end_clean(); // Strip out PHP delmiter, if we added it if (!$delimiter) { $colored_example = str_replace( array ( '<font color="#0000CC"><?php </font>', '<?php ', '<font color="#0000CC">?></font>' ), array ('', '', ''), $colored_example ); } // Get much smaller source code by converting // display identical things to smaller size $colored_example = str_replace( array("\n", "<code>", "</code>", " ", "<br />"), array("", "", "", " ", "\n"), $colored_example ); // Pre container to strip out uneeded font tags $colored_example = '<pre>' . $colored_example . '</pre>'; $colored_example = str_replace( array('<pre><font color="#000000">', '</font></pre>'), array('', ''), $colored_example ); // Get color settings $color_settings = array( '<span class="cs">' => '<font color="' . ini_get("highlight.string") . '">', '<span class="cc">' => '<font color="' . ini_get("highlight.comment") . '">', '<span class="ck">' => '<font color="' . ini_get("highlight.keyword") . '">', '<span class="cb">' => '<font color="' . ini_get("highlight.bg") . '">', '<span class="cd">' => '<font color="' . ini_get("highlight.default") . '">', '<span class="ch">' => '<font color="' . ini_get("highlight.html") . '">', '</span>' => '</font>' ); // Convert colors to classes spaned $colored_example = str_replace( array_values($color_settings), array_keys($color_settings), $colored_example ); // Try to find function names so they can be linked // This patterns is what we are searching for: // <span class="cd">array_keys </span><span class="ck">( $colored_example = links2Examples( '!<span class="cd">([a-z0-9_]+)\s*</span><span class="ck">\(!Us', $colored_example, 1, 'cd' ); // control structures or other keywords, like // exit, print with possibly something before // and after them // Note: I do not link if, else and the // other control structures in, because they are // too common, and linking them would clutter up // the examples $colored_example = links2Examples( '!<span class="ck">[^<]*(<br>)?[^<]*' . '(exit|die|echo|print|empty|isset|unset|break|continue' . '|static|global|array)[^<]*' . '</span>!Us', $colored_example, 2, 'ck' ); // Return with the converted example return $linkwdiv . '<code id="example_' . $preNum . '">' . pre2code($colored_example) . '</code></div><p>'; } // formatPre() function end // Convert <pre> contained code to text for the <code> container function pre2code ($text) { return str_replace( array(' ', "\n"), array(' ', "<br>\n"), $text ); } // pre2code() function end // Find string matching a regexp and make function/control // structures/keywords links function links2Examples($regexp, $example, $idx, $class) { global $HTML_SRC; // Try to find matching text in $example if (preg_match_all($regexp, $example, $found)) { // This is where we store all text to replace, // [original text and replacement text] $replace_array = array( 0 => array(), 1 => array() ); // Loop through all function names, and try to find a file // for them (they can be user defined functions) foreach ($found[$idx] as $num => $reptext) { // The main part of this filename $filepart = strtolower(str_replace("_", "-", $reptext)); // Possible full filenames $files = array( "function.$filepart.html", "class.$filepart.html", "control-structures.$filepart.html" ); // Guess what should be the filename for this foreach ($files as $filename) { // If this file exists, then we are OK if (@file_exists("$HTML_SRC/$filename")) { $replace_array[0][] = $found[0][$num]; $replace_array[1][] = str_replace( $reptext, "<a href=\"$filename\" class=\"$class\">$reptext</a>", $found[0][$num] ); break; } } } // Perform string replacement on example content, // only replace functions where we can link $example = str_replace( $replace_array[0], $replace_array[1], $example ); } // Maybe we modified something, maybe not. // Return with the current $example text. return $example; } // links2Examples() function end ?> Index: phpdoc/htmlhelp/local_vars.php +++ phpdoc/htmlhelp/local_vars.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. Please provide all directory values without a trailing backslash. Paths are relative to the "phpdoc\htmlhelp" directory. Be sure, not to give any directory or file names with spaces in them. */ /* This must be a valid language code used in the phpdoc repository. Defaults to en. */ $LANGUAGE = 'en'; /* This must be the path including the executable file's name of the hhc.exe included in Microsoft HTML Help Workshop. The default is 'c:\\progra~1\\_development\\htmlhe~1\\hhc.exe'. */ $HELP_WORKSHOP = 'c:\\progra~1\\_development\\htmlhe~1\\hhc.exe'; /* This must be the directory, where the XSL generated HTML files and hh[pkc] supplemental files can be found. The defaults is 'html', the html output dir used by HTMLHelp XSL style sheets. */ $HTML_SRC = 'html'; /* This is the directory, where the files generated by this system should go. The default is 'htmlout'. Beware, that if you set this to the same as the above, the start cleanup will delete your source files (so you need to set $START_CLEANUP to FALSE in that case!) */ $HTML_TARGET = 'htmlout'; /* This must be a valid directory name, where the manual note sources can be found. The default is 'notesin' (a directory under "phpdoc\htmlhelp"). */ $NOTES_SRC = 'notesin'; /* This is the directory name, where the HTML files for the notes help file go. The default is 'notesout' (a directory under "phpdoc\htmlhelp"). It is created if nonexistent. */ $NOTES_TARGET = 'notesout'; /* This is the directory name, where all the release files will go. The default is 'release' (a directory under "phpdoc\htmlhelp"). It is created if nonexistent. */ $RELEASE_DIR = 'release'; /* This must be TRUE or FALSE, depending on whether you would like to use notes sources to build a "php_manual_notes.chm" output file or not. The default is to generate a note file. Note, that it is only safe to generate a notes file with the English version, as it has all the pages, while other translations don't have them, so using them as note bases would cause note data loss. */ $USE_NOTES = TRUE; /* This must be TRUE or FALSE, depending on whether you would like the script to do automatic cleanup on startup. The script cleans up all working directories, except $HTML_SRC, where the sources of this script are. This means that $HTML_TARGET, $NOTES_SRC, $NOTES_TARGET and $RELEASE_DIR folders are emptyed if this is TRUE. */ $START_CLEANUP = TRUE; /* Deletes all work files except the files in $RELEASE_DIR. This means that all the $HTML_SRC, $HTML_TARGET, $NOTES_SRC and $NOTES_TARGET directories are emptyed. You probably never want to do this, if you are developing the system, as all the HTML source files generated by "make" will be lost, and you need to start over again from make. */ $END_CLEANUP = FALSE; ?> Index: phpdoc/htmlhelp/local_vars.php.src +++ phpdoc/htmlhelp/local_vars.php.src <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. Please provide all directory values without a trailing backslash. Paths are relative to the "phpdoc\htmlhelp" directory. Be sure, not to give any directory or file names with spaces in them. */ /* This must be a valid language code used in the phpdoc repository. Defaults to en. */ $LANGUAGE = 'en'; /* This must be the path including the executable file's name of the hhc.exe included in Microsoft HTML Help Workshop. The default is 'c:\\progra~1\\_development\\htmlhe~1\\hhc.exe'. */ $HELP_WORKSHOP = 'c:\\progra~1\\_development\\htmlhe~1\\hhc.exe'; /* This must be the directory, where the XSL generated HTML files and hh[pkc] supplemental files can be found. The defaults is 'html', the html output dir used by HTMLHelp XSL style sheets. */ $HTML_SRC = 'html'; /* This is the directory, where the files generated by this system should go. The default is 'htmlout'. Beware, that if you set this to the same as the above, the start cleanup will delete your source files (so you need to set $START_CLEANUP to FALSE in that case!) */ $HTML_TARGET = 'htmlout'; /* This must be a valid directory name, where the manual note sources can be found. The default is 'notesin' (a directory under "phpdoc\htmlhelp"). */ $NOTES_SRC = 'notesin'; /* This is the directory name, where the HTML files for the notes help file go. The default is 'notesout' (a directory under "phpdoc\htmlhelp"). It is created if nonexistent. */ $NOTES_TARGET = 'notesout'; /* This is the directory name, where all the release files will go. The default is 'release' (a directory under "phpdoc\htmlhelp"). It is created if nonexistent. */ $RELEASE_DIR = 'release'; /* This must be TRUE or FALSE, depending on whether you would like to use notes sources to build a "php_manual_notes.chm" output file or not. The default is to generate a note file. Note, that it is only safe to generate a notes file with the English version, as it has all the pages, while other translations don't have them, so using them as note bases would cause note data loss. */ $USE_NOTES = TRUE; /* This must be TRUE or FALSE, depending on whether you would like the script to do automatic cleanup on startup. The script cleans up all working directories, except $HTML_SRC, where the sources of this script are. This means that $HTML_TARGET, $NOTES_SRC, $NOTES_TARGET and $RELEASE_DIR folders are emptyed if this is TRUE. */ $START_CLEANUP = TRUE; /* Deletes all work files except the files in $RELEASE_DIR. This means that all the $HTML_SRC, $HTML_TARGET, $NOTES_SRC and $NOTES_TARGET directories are emptyed. You probably never want to do this, if you are developing the system, as all the HTML source files generated by "make" will be lost, and you need to start over again from make. */ $END_CLEANUP = FALSE; ?> Index: phpdoc/htmlhelp/make_chm.bat +++ phpdoc/htmlhelp/make_chm.bat @php -f make_chm.php Index: phpdoc/htmlhelp/make_chm.php +++ phpdoc/htmlhelp/make_chm.php <?php /* This is the main file of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. Written by Gabor Hojtsy <goba@php.net> Credits go to people worked on previous versions: Derick Rethans, Jirka Kosek, Thomas Schoefbeck and Harald Radi */ // Measure needed time $start_time = time(); // This script can take much time to run set_time_limit(0); // Include variables used by the build process // Test for local_vars, as they are not there by default if (!@file_exists("local_vars.php")) { die("ERROR: local_vars.php is needed, but not there"); } require_once "local_vars.php"; // Possible languages for manual generation $LANGUAGES = array( "cs", "de", "en", "es", "fr", "hu", "it", "ja", "kr", "nl", "pt_BR" ); echo " ____________________________________________________________ Generate Microsoft HTML Help document from the output of XSL generated HTML files of the PHP documentation. See \"local_vars.php.src\" for local parameter adjustment, see README.txt and the phpdoc howto for more information. ____________________________________________________________ "; // Process parameters echo "\n| Processing local parameters...\n"; if (!@is_dir($HTML_SRC)) { die("ERROR: HTML path not valid"); } if (!@file_exists($HELP_WORKSHOP)) { die("ERROR: HTML Workshop path not valid"); } if (!@is_dir($RELEASE_DIR)) { mkdir($RELEASE_DIR, 0700); echo "> $RELEASE_DIR directory created...\n"; } elseif ($START_CLEANUP) { echo "| Cleaning up $RELEASE_DIR directory...\n"; passthru("rmdir /S /Q $RELEASE_DIR"); mkdir($RELEASE_DIR, 0700); } if (!@is_dir($HTML_TARGET)) { mkdir($HTML_TARGET, 0700); echo "> $HTML_TARGET directory created...\n"; } elseif ($START_CLEANUP) { echo "| Cleaning up $HTML_TARGET directory...\n"; passthru("rmdir /S /Q $HTML_TARGET"); mkdir($HTML_TARGET, 0700); } if ($USE_NOTES) { if (!@is_dir($NOTES_SRC)) { mkdir($NOTES_SRC, 0700); echo "> $NOTES_SRC directory created...\n"; } elseif ($START_CLEANUP) { echo "| Cleaning up $NOTES_SRC directory...\n"; passthru("rmdir /S /Q $NOTES_SRC"); mkdir($NOTES_SRC, 0700); } if (!@is_dir($NOTES_TARGET)) { mkdir($NOTES_TARGET, 0700); echo "> $NOTES_TARGET directory created...\n"; } elseif ($START_CLEANUP) { echo "| Cleaning up $NOTES_TARGET directory...\n"; passthru("rmdir /S /Q $NOTES_TARGET"); mkdir($NOTES_TARGET, 0700); } echo "| php_manual_notes.chm target choosen...\n"; if ($LANGUAGE != 'en') { echo "| Warning: it is not safe to generate notes CHM for non-english HTML files\n"; } } // Test for mirror information file if (!file_exists("mirrors.inc")) { die("ERROR: Mirror information file (mirrors.inc) not found"); } // Generate files and compile echo "| Parameters processed... "; echo " > Now the HTML files are being filtered to make output as perfect as possible. Please be patient, as it can take some time... "; $counter = 0; require_once "filter_files.php"; echo "> $counter files are converted in previous step. "; if ($USE_NOTES) { $WITH_NOTES = $WITHOUT_NOTES = $NOTE_NUM = 0; echo " > Trying to split user notes 'all' file to separate directories and files (to make the next step fast and less resource intensive)... "; require_once "split_notes.php"; echo " > Now the user notes project file and HTML files are being created. Please be patient, as it can take as much time as the previous step... "; require_once "user_notes.php"; echo "> $WITH_NOTES files created with notes $WITHOUT_NOTES files found without notes Total number of notes: $NOTE_NUM "; } echo " > Now creating mirrors.ini file from current mirrors.inc... "; require_once "mirrors_ini.php"; echo " > Now starting HTML Help Workshop... ____________________________________________________________ "; // Run HTML Help Workshop, and move files to release directory passthru($HELP_WORKSHOP . " $HTML_TARGET\\php_manual_$LANGUAGE.hhp"); rename("$HTML_TARGET/php_manual_$LANGUAGE.chm", "$RELEASE_DIR/php_manual_$LANGUAGE.chm"); if ($USE_NOTES) { passthru($HELP_WORKSHOP . " $NOTES_TARGET\\php_manual_notes.hhp"); rename("$NOTES_TARGET/php_manual_notes.chm", "$RELEASE_DIR/php_manual_notes.chm"); } // Copy PHP manual preferences, qucikref and skins files to release directory // $RELEASE_DIR = str_replace("/", "\\", $RELEASE_DIR): exec("copy suppfiles\\prefs $RELEASE_DIR /Y"); exec("copy suppfiles\\quickref $RELEASE_DIR /Y"); exec("copy suppfiles\\fixes $RELEASE_DIR /Y"); exec("xcopy /S /I /Q suppfiles\\skins $RELEASE_DIR\\skins"); // Delete unused files if ($END_CLEANUP) { echo "> Removing every file except the release files...\n"; passthru("rmdir /S /Q $HTML_SRC"); passthru("rmdir /S /Q $HTML_TARGET"); passthru("rmdir /S /Q $NOTES_SRC"); passthru("rmdir /S /Q $NOTES_TARGET"); } // Measure time $alltime = time() - $start_time; echo "____________________________________________________________\n"; echo "Conversion done in " . ((int) ($alltime / 60)) . " minutes "; echo "and " . $alltime % 60 . " seconds.\n"; echo "You can find the generated file[s] in $RELEASE_DIR directory\n"; echo "____________________________________________________________\n"; ?> Index: phpdoc/htmlhelp/mirrors_ini.php +++ phpdoc/htmlhelp/mirrors_ini.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. This script generates mirrors.ini from mirrors.inc ( can be downloaded from http://MIRROR.php.net/include/mirrors.inc ) */ // Load the mirrors file in include_once "mirrors.inc"; // Get mirror site addresses $mirrors = array_keys($MIRRORS); // Write out mirror information $fp = fopen($RELEASE_DIR . "/mirrors.ini", "w"); fwrite($fp, "# ================================================= # PHP Manual CHM version mirror list configuration # ================================================= # Possible mirrors for online functions (only those # mirrors are listed, which were active when this # list was generated) [mirrors] "); // Write out all active mirror sites foreach ($MIRRORS as $mirror => $mirrrorinfo) { if ($mirrorinfo[7] == MIRROR_OK) { fwrite($fp, "mirror = \"$mirror\"\n"); } } fclose($fp); ?> Index: phpdoc/htmlhelp/README.txt +++ phpdoc/htmlhelp/README.txt Build system of the new CHMs ============================ [See latest "official" output package online at http://weblabor.hu/php-doc-chm] How to build a CHM manual with this system? 1. run "autoconf" in the phpdoc directory 2. run "./configure --with-chm=yes --with-xsl=yes" Optionally you may need to specify the "--with-xsltproc=path" option to explicitly provide the XSLTProc path. 3. Run "make chm_xsl" If xsltproc encounters errors in the XML files, correct the errors, commit them to phpdoc, and run "make chm_xsl" again. There is no need to reconfigure in most cases. After this step the HTML files to start are in phpdoc/htmlhelp/html 4. Get the actual mirrors.inc file from http://ANY_MIRROR.php.net/include/mirrors.inc and save into the directory where the make_chm.bat resides (overwrite old one if one exists). 6. Get all the user notes from http://ANY_MIRROR.php.net/backend/notes/ALL.bz2, extract it's contents, and place the resulting "all" file to the same folder where the make_chm.bat resides. 7. Copy local_vars.php.src to local_vars.php and adjust settings as needed. 8. Now run make_chm.bat Well, this is quite manual right now, and there are some problems need fixing (see the TODO.txt file too). Index: phpdoc/htmlhelp/split_notes.php +++ phpdoc/htmlhelp/split_notes.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. This code splits up the notes file to be easily processeable by the notes CHM generator script. */ // Check for previous run if (@is_dir("$NOTES_SRC/0")) { echo "\n> Previous user note split detected, skipping\n"; } // We have no splitted notes files, do it now else { // Open all notes source file for reading $fp = @fopen("all", "r"); if (!$fp) { die("ERROR: No all notes file present"); } // Read through the file, and write individual files while (!feof($fp)) { $line = chop(fgets($fp,8096)); if ($line == "") continue; // Get data from one line list($id,$sect,$rate,$ts,$user,$note) = explode("|",$line); $hash = substr(md5($sect),0,16); // Create dir if nonexistent if (!@is_dir("$NOTES_SRC/" . $hash[0])) { mkdir("$NOTES_SRC/" . $hash[0], 0700); } // Append line to appropriate file $nf = fopen("$NOTES_SRC/" . $hash[0] . "/$hash", "a"); fwrite($nf, $line . "\n"); fclose($nf); } // Close all notes file fclose($fp); } ?> Index: phpdoc/htmlhelp/TODO.txt +++ phpdoc/htmlhelp/TODO.txt ! Please contact goba@php.net before modifying ! the code in the "htmlhelp" folder in CVS. Important: - Add _function.html to the resulting CHM, which can redirect to a function page in the CHM. IDEs without direct PHP manual support can use this to integrate the CHM. - Make the build system support other languages then English. All the strings used need to be customizable. This also includes the porting of the charset conversion added lately to the "old chm" build system. - Make the build system run more automatically. Additional: - Do not clean up the notesin and notesout directories if recently generated files are there (the "all" file is older then those files generated there). - Also do not clean up the "htmlout" directory if the files there are newer then the ones in the "html" directory. - Implement some detection for the $HTML_SRC and $HTML_TARGET directories, and don't do cleanups, and some copying, if they are the same. - Experiment with Brendan Ferguson's JS syntax highlighter and test it's usage in user note coloring. This would make the resulting CHMs much smaller, but needs JS magic (may be slow). - Document the skin framework, how it works, so others will be able to create their own skins. Index: phpdoc/htmlhelp/user_notes.php +++ phpdoc/htmlhelp/user_notes.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. The logic in this file comes from an extract of phpweb/include/shared-manual.inc and phpweb/include/layout.inc (clean_note()). From time to time, it may be needed to update the code, as the manual notes system changes. This file is consistent with: layout.inc - 1.66 shared-manual.inc - 1.125 This file also includes code to generate a project file for the notes. Grab the notes file (all compressed) from: http://ANY_MIRROR_SITE.php.net/backend/notes/all.bz2 */ // Check dependencies, die if error found if (!$USE_NOTES) { die("ERROR: User note generator called"); } // Merge all possible language manuals. Only the available // manual[s] will be active, while viewing $lang_chms = ''; foreach ($LANGUAGES as $code) { $lang_chms .= "php_manual_$code.chm\n"; } // We need a list of files for an IE6 workaround $NOTE_FILE_LIST = array(); // Start writing the notes project file $nproject = fopen("$NOTES_TARGET/php_manual_notes.hhp", "w"); fputs($nproject, "[OPTIONS] Compatibility=1.1 or later Compiled file=php_manual_notes.chm Default topic=_index.html Display compile progress=No Full-text search=Yes Language=0x0809 English (UNITED KINGDOM) Title=User Notes [MERGE FILES] $lang_chms [FILES] "); // Walk through all files in HTML_DIR directory $handle = opendir($HTML_SRC); while (false !== ($filename = readdir($handle))) { // Only process html files generated by XSL sheets if (strpos($filename, ".html") && (strpos($filename, "_") !== 0)) { // Get title (used for HTML page title) $content = join("", file("$HTML_SRC/$filename")); preg_match("!<title>([^<]+)</title>!Us", $content, $match); // Get user notes, or false on failure $user_notes = manualUserNotes($match[1], $filename); // If there are no user notes for this page, // no file will be generated, but if we generate // a file, we add it to project file too if ($user_notes != FALSE) { $WITH_NOTES++; $notes = fopen("$NOTES_TARGET/$filename", "w"); fwrite($notes, $user_notes); fclose($notes); fwrite($nproject, $filename . "\n"); $NOTE_FILE_LIST[] = $filename; echo "> $WITH_NOTES\r"; } else { $WITHOUT_NOTES++; } } } closedir($handle); // Copy note supplemental files, and add to file list copy("suppfiles/notes/_index.html", "$NOTES_TARGET/_index.html"); fwrite($nproject, "_index.html\n"); copy("suppfiles/notes/_style.css", "$NOTES_TARGET/_style.css"); fwrite($nproject, "_style.css\n"); // Write out a list of files to work around an IE6 bug $jsfile = fopen("$NOTES_TARGET/_filelist.js", "w"); fwrite($jsfile, "note_file_list = '" . join(" ", $NOTE_FILE_LIST) . "';\n\n"); fwrite($jsfile, "if (note_file_list.indexOf(chmfile_page) != -1) { notesIframe(); }"); fclose($jsfile); fwrite($nproject, "_filelist.js\n"); // Close ready project file fclose($nproject); // Make entry HTML fragment for a user note function makeEntry($date, $name, $blurb) { // Begin user notes header $entryhtml = "<div><p class=\"unheader\">\n"; // Get email/name of the user note writer $name = htmlspecialchars($name); if ($name && $name != "php-general@lists.php.net" && $name != "user@example.com") { if (ereg("(.+)@(.+)\.(.+)", $name)) { $entryhtml .= "<a href=\"mailto:$name\" class=\"useremail\"><span>$name</span></a>"; } else { $entryhtml .= "<b><span>$name</span></b>"; } } // Append date $entryhtml .= " (<span>" . date("d-M-Y h:i", $date) . "</span>)</p>\n"; // Append user note text, cleared $entryhtml .= "<p class=\"untext\"><tt><span>" . clean_note($blurb) . "</span></tt></p></div>\n"; // Return with entry HTML fragment return $entryhtml; } // Get user notes for this particular page, returns an array with notes function manualGetUserNotes($id) { global $NOTES_SRC, $NOTE_NUM; $notes = array(); $hash = substr(md5($id),0,16); $notes_file = "$NOTES_SRC/$hash[0]/$hash"; if ($fp = @fopen($notes_file,"r")) { while (!feof($fp)) { $line = chop(fgets($fp,8096)); if ($line == "") continue; list($id,$sect,$rate,$ts,$user,$note) = explode("|",$line); $notes[] = array( "id" => $id, "sect" => $sect, "rate" => $rate, "xwhen" => $ts, "user" => $user, "note" => base64_decode($note) ); } fclose($fp); } $NOTE_NUM += count($notes); return $notes; } // Get the HTML file for a user note page, or false on failure function manualUserNotes($title, $id) { // Don't want .html at the end of the ids if (substr($id,-5) == '.html') { $id = substr($id,0,-5); } // Get user notes $notes = manualGetUserNotes($id); // If we have no notes, do not produce useless HTML if (count($notes) == 0) { return FALSE; } // start HTML output $notehtml = <<<END_OF_MULTI <html> <head> <title>N: $title</title> <link rel="stylesheet" href="_style.css"> </head> <body onLoad="if(parent.nbuff) {parent.displayNotes()}"> <h3>User contributed notes:</h3> END_OF_MULTI; // Go through manual notes, and make entries foreach ($notes as $note) { $notehtml .= makeEntry($note['xwhen'], $note['user'], $note['note'], $note['id']); } // Be good guys, and end HTML code here $notehtml .= "\n</body></html>"; // Return with manual notes for this page return $notehtml; } // Clean note to get right display function clean_note($text) { // Do not allow people to fool the system with bogus HTML $text = htmlspecialchars(trim($text)); // turn urls into links $text = preg_replace("/((mailto|http|ftp|nntp|news):.+?)(>|\\s|\\)|\"|\\.\\s|$)/","<a href=\"\\1\">\\1</a>\\3",$text); // this 'fixing' code will go away eventually $fixes = array('<br>','<p>','</p>'); reset($fixes); while (list(,$f)=each($fixes)) { $text=str_replace(htmlspecialchars($f), $f, $text); $text=str_replace(htmlspecialchars(strtoupper($f)), $f, $text); } // Allow only one <br> (drop out long empty sections) $text = preg_replace("!(<br>\\s*)+!", "<br>", $text); // wordwrap is not applicable here, because (it is buggy and) // we need to make text break as window resized // Convert new lines in notes to <br> / <br /> $text = nl2br(preg_replace("![\\n\\r]+!", "\n", $text)); // Get files to smaller size (bad hack :) $text = str_replace("<br />", "<br>", $text); // We do not use <pre> but would like to see indentation $text = str_replace(" ", " ", $text); // Paras cannot be used here, replace with <br><br> $text = str_replace("<p>", "<br><br>", $text); // Drop out end of paras $text = str_replace("</p>", "", $text); return $text; } ?>
Index: phpdoc/htmlhelp/.cvsignore +++ phpdoc/htmlhelp/.cvsignore html htmlout notesin notesout release local_vars.php mirrors.inc all Index: phpdoc/htmlhelp/filter_files.php +++ phpdoc/htmlhelp/filter_files.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. The filters included in this file are to refine the XSL generated HTML codes. Some filters may be converted to XSL templates, but not all. */ $counter = filterFiles(); // Filter XSL generated files through some refine filters function filterFiles() { global $HTML_SRC, $HTML_TARGET, $INDEX_FILE; // How many files were processed $counter = 0; // Try to figure out what index file to use if (file_exists("$HTML_SRC/index.html")) { $INDEX_FILE = "index.html"; } else { $INDEX_FILE = "manual.html"; } // Open the directory, and do the work on all HTML files $handle = opendir($HTML_SRC); while (false !== ($filename = readdir($handle))) { // Only process html files if (strpos($filename, ".html")) { $counter++; refineFile($filename); echo "> $counter\r"; } } closedir($handle); // Open supplemental files directory, and copy // all files to output directory $handle = opendir("./suppfiles/html/"); while (false !== ($filename = readdir($handle))) { if (!in_array($filename, array(".", ".."))) { copy("suppfiles/html/$filename", "$HTML_TARGET/$filename"); $counter++; echo "> $counter\r"; } } closedir($handle); // Copy source Help files from html dir to output dir copy("$HTML_SRC/php_manual_en.hhp", "$HTML_TARGET/php_manual_en.hhp"); copy("$HTML_SRC/php_manual_en.hhc", "$HTML_TARGET/php_manual_en.hhc"); copy("$HTML_SRC/php_manual_en.hhk", "$HTML_TARGET/php_manual_en.hhk"); return $counter; } // filterFiles() function end // Refine HTML code in XSL generated files function refineFile($filename) { global $HTML_SRC, $HTML_TARGET, $INDEX_FILE, $preNum; // The number of <pre> parts is zero (used for example copy links) $preNum = 0; // Read in the contents of the source file $content = join("", file("$HTML_SRC/$filename")); //------------------------------------------------------------------ // Find page title and format it properly preg_match('!<title>\s*(.+)</title>!Us', $content, $matched); $page_title = $matched[1]; // Replace title with simple <title> content [shorter, without tags] $content = preg_replace( '!<h(\d)[^>]*>.+</h\1>!Us', "<h1 class=\"masterheader\"><span id=\"pageTitle\">$page_title</span></h1>", $content, 1 ); //------------------------------------------------------------------ // Add divisions for skin support // Make the document invisible by default, adding a new first div $content = preg_replace( '!(<div class="(\w+)">)!Us', '<div id="pageContent" style="display:none;">\1<div id="pageHeaders">', $content, 1 ); // Put there the end of this pageContent $content = str_replace( '</body></html>', '</div></body></html>', $content ); // For headers we have several possibilities if (strpos($content, '<div class="refnamediv">') !== FALSE) { // A function page if (!strpos($content, "refsynopsisdiv")) { $content = str_replace( '</h2></div><div class="refsect1">', '</h2></div></div><div id="pageText"><div class="refsect1">', $content ); } // The COM or VARIANT classes page (which contain refsynopsisdiv) else { $content = str_replace( '<div class="refsynopsisdiv">', '</div><div id="pageText"><div class="refsynopsisdiv">', $content ); } } // Normal page, and not an index elseif ($filename != $INDEX_FILE) { $content = preg_replace( '!</h1></div>(<p>)?</div>!', '</h1></div>\\1</div></div><div id="pageText">', $content ); } // The index page else { // Delete titlepage div and // add pageHeader end and pageText start $content = str_replace( array("<div class=\"titlepage\">", "<hr></div>"), array("", "<hr>"), $content ); $content = preg_replace( '!</h1></div><div>!', '</h1></div></div><div id="pageText"><div>', $content ); } // End that pageText div before the user notes $content = str_replace( '<a name="_user_notes">', '</div><a name="_user_notes">', $content ); // If this is the index file, correct it if ($filename == $INDEX_FILE) { $content = newIndex($content); } //------------------------------------------------------------------ // Change pre sections look (examples, screen outputs, etc). $content = preg_replace_callback( '!<pre class="([^"]+)">(.+)</pre>!Us', "formatPre", $content ); //------------------------------------------------------------------ // Put <p> tags after all </ul> or </div> or </table> close tags to // enable CSS support for those paragraphs (these break a <p>) // BUT do not put a P after our special notes container $content = preg_replace('!</(ul|div|table)>!Us', '</\\1><p>', $content); $content = str_replace('<div id="pageNotes"></div><p>', '<div id="pageNotes"></div>', $content); //------------------------------------------------------------------ // Delete duplicate <p> tags from code, unneded <p></p> parts, and // <p> before <table> or <div> or </div> or </body> or <ul> $content = preg_replace('!<p>\s*<p>!Us', '<p>', $content); $content = preg_replace('!<p>\s*</p>!Us', '', $content); $content = preg_replace('!<p>\s*<(table|div|/div|/body|ul)!Us', '<\\1', $content); //------------------------------------------------------------------ // Drop out all the <div> and </div> tags left (no need to have them) //$content = preg_replace('!</?div[^>]*>!Us', '', $content); // !!! Temporary fix for XSLT output escaping problems $content = preg_replace("!&raquo; !", "» ", $content); //------------------------------------------------------------------ // Write out file to HTML output directory $fp = fopen("$HTML_TARGET/$filename", "w"); fwrite($fp, $content); fclose($fp); } // newFace() function end // Make the old index look somewhat better function newIndex ($content) { global $HTML_TARGET; // Get contents we need to build the _index.html file preg_match("!^(.+)<hr>!s", $content, $_index1); preg_match("!(</div></div><a name=\"_user_notes\">.+</html>)!s", $content, $_index2); // Write out the two components to form a complete file $fp = fopen("$HTML_TARGET/_index.html", "w"); fwrite($fp, $_index1[1] . $_index2[1]); fclose($fp); // Drop out authors list (this is on the frontpage) $content = preg_replace( '!<div id="pageText"><div>.*<hr>!Us', '<div id="pageText">', $content ); // Get TOC title from HTML code preg_match( '!<div class="toc"><p><b>(.+)</b></p>!U', $content, $match ); // Put toc title into title places $content = preg_replace( '!<title>(.+)</title>!U', "<title>$match[1]</title>", $content ); $content = preg_replace( '!<span id="pageTitle">(.+)</span>!U', "<span id=\"pageTitle\">$match[1]</span>", $content ); // Drop out small TOC title $content = preg_replace( '!<div class="toc"><p><b>(.+)</b></p>!U', '<div class="toc">', $content ); return $content; } // newIndex() function end // Change pre sections look function formatPre () { // Number of <pre> sections on this page global $preNum; // Construct clipboard copy link $preNum++; $linkwdiv = '<div class="codelink"><a href="javascript:void(0);" onclick="copyExample(\'' . $preNum . '\')">copy to clipboard</a></div><div class="examplecode">'; // Replace all hard line breaks list($pre_found) = func_get_args(); // Not a PHP example if ($pre_found[1] != 'php') { return $linkwdiv . '<code id="example_' . $preNum . '">' . pre2code(trim($pre_found[2])) . '</code></div><p>'; } // Convert entities to characters for color coding $example = str_replace( array(">", "<", "&", """), array(">", "<", "&", "\""), $pre_found[2] ); // Trim example code to get rid of extra line breaks $example = trim($example); // Start output buffer, add PHP tags if none is there ob_start(); if (!strstr($example, "<?php")) { $example = "<?php " . $example . " ?>"; $delimiter = FALSE; } else { $delimiter = TRUE; } // Get highlited source code highlight_string($example); $colored_example = ob_get_contents(); ob_end_clean(); // Strip out PHP delmiter, if we added it if (!$delimiter) { $colored_example = str_replace( array ( '<font color="#0000CC"><?php </font>', '<?php ', '<font color="#0000CC">?></font>' ), array ('', '', ''), $colored_example ); } // Get much smaller source code by converting // display identical things to smaller size $colored_example = str_replace( array("\n", "<code>", "</code>", " ", "<br />"), array("", "", "", " ", "\n"), $colored_example ); // Pre container to strip out uneeded font tags $colored_example = '<pre>' . $colored_example . '</pre>'; $colored_example = str_replace( array('<pre><font color="#000000">', '</font></pre>'), array('', ''), $colored_example ); // Get color settings $color_settings = array( '<span class="cs">' => '<font color="' . ini_get("highlight.string") . '">', '<span class="cc">' => '<font color="' . ini_get("highlight.comment") . '">', '<span class="ck">' => '<font color="' . ini_get("highlight.keyword") . '">', '<span class="cb">' => '<font color="' . ini_get("highlight.bg") . '">', '<span class="cd">' => '<font color="' . ini_get("highlight.default") . '">', '<span class="ch">' => '<font color="' . ini_get("highlight.html") . '">', '</span>' => '</font>' ); // Convert colors to classes spaned $colored_example = str_replace( array_values($color_settings), array_keys($color_settings), $colored_example ); // Try to find function names so they can be linked // This patterns is what we are searching for: // <span class="cd">array_keys </span><span class="ck">( $colored_example = links2Examples( '!<span class="cd">([a-z0-9_]+)\s*</span><span class="ck">\(!Us', $colored_example, 1, 'cd' ); // control structures or other keywords, like // exit, print with possibly something before // and after them // Note: I do not link if, else and the // other control structures in, because they are // too common, and linking them would clutter up // the examples $colored_example = links2Examples( '!<span class="ck">[^<]*(<br>)?[^<]*' . '(exit|die|echo|print|empty|isset|unset|break|continue' . '|static|global|array)[^<]*' . '</span>!Us', $colored_example, 2, 'ck' ); // Return with the converted example return $linkwdiv . '<code id="example_' . $preNum . '">' . pre2code($colored_example) . '</code></div><p>'; } // formatPre() function end // Convert <pre> contained code to text for the <code> container function pre2code ($text) { return str_replace( array(' ', "\n"), array(' ', "<br>\n"), $text ); } // pre2code() function end // Find string matching a regexp and make function/control // structures/keywords links function links2Examples($regexp, $example, $idx, $class) { global $HTML_SRC; // Try to find matching text in $example if (preg_match_all($regexp, $example, $found)) { // This is where we store all text to replace, // [original text and replacement text] $replace_array = array( 0 => array(), 1 => array() ); // Loop through all function names, and try to find a file // for them (they can be user defined functions) foreach ($found[$idx] as $num => $reptext) { // The main part of this filename $filepart = strtolower(str_replace("_", "-", $reptext)); // Possible full filenames $files = array( "function.$filepart.html", "class.$filepart.html", "control-structures.$filepart.html" ); // Guess what should be the filename for this foreach ($files as $filename) { // If this file exists, then we are OK if (@file_exists("$HTML_SRC/$filename")) { $replace_array[0][] = $found[0][$num]; $replace_array[1][] = str_replace( $reptext, "<a href=\"$filename\" class=\"$class\">$reptext</a>", $found[0][$num] ); break; } } } // Perform string replacement on example content, // only replace functions where we can link $example = str_replace( $replace_array[0], $replace_array[1], $example ); } // Maybe we modified something, maybe not. // Return with the current $example text. return $example; } // links2Examples() function end ?> Index: phpdoc/htmlhelp/local_vars.php +++ phpdoc/htmlhelp/local_vars.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. Please provide all directory values without a trailing backslash. Paths are relative to the "phpdoc\htmlhelp" directory. Be sure, not to give any directory or file names with spaces in them. */ /* This must be a valid language code used in the phpdoc repository. Defaults to en. */ $LANGUAGE = 'en'; /* This must be the path including the executable file's name of the hhc.exe included in Microsoft HTML Help Workshop. The default is 'c:\\progra~1\\_development\\htmlhe~1\\hhc.exe'. */ $HELP_WORKSHOP = 'c:\\progra~1\\_development\\htmlhe~1\\hhc.exe'; /* This must be the directory, where the XSL generated HTML files and hh[pkc] supplemental files can be found. The defaults is 'html', the html output dir used by HTMLHelp XSL style sheets. */ $HTML_SRC = 'html'; /* This is the directory, where the files generated by this system should go. The default is 'htmlout'. Beware, that if you set this to the same as the above, the start cleanup will delete your source files (so you need to set $START_CLEANUP to FALSE in that case!) */ $HTML_TARGET = 'htmlout'; /* This must be a valid directory name, where the manual note sources can be found. The default is 'notesin' (a directory under "phpdoc\htmlhelp"). */ $NOTES_SRC = 'notesin'; /* This is the directory name, where the HTML files for the notes help file go. The default is 'notesout' (a directory under "phpdoc\htmlhelp"). It is created if nonexistent. */ $NOTES_TARGET = 'notesout'; /* This is the directory name, where all the release files will go. The default is 'release' (a directory under "phpdoc\htmlhelp"). It is created if nonexistent. */ $RELEASE_DIR = 'release'; /* This must be TRUE or FALSE, depending on whether you would like to use notes sources to build a "php_manual_notes.chm" output file or not. The default is to generate a note file. Note, that it is only safe to generate a notes file with the English version, as it has all the pages, while other translations don't have them, so using them as note bases would cause note data loss. */ $USE_NOTES = TRUE; /* This must be TRUE or FALSE, depending on whether you would like the script to do automatic cleanup on startup. The script cleans up all working directories, except $HTML_SRC, where the sources of this script are. This means that $HTML_TARGET, $NOTES_SRC, $NOTES_TARGET and $RELEASE_DIR folders are emptyed if this is TRUE. */ $START_CLEANUP = TRUE; /* Deletes all work files except the files in $RELEASE_DIR. This means that all the $HTML_SRC, $HTML_TARGET, $NOTES_SRC and $NOTES_TARGET directories are emptyed. You probably never want to do this, if you are developing the system, as all the HTML source files generated by "make" will be lost, and you need to start over again from make. */ $END_CLEANUP = FALSE; ?> Index: phpdoc/htmlhelp/local_vars.php.src +++ phpdoc/htmlhelp/local_vars.php.src <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. Please provide all directory values without a trailing backslash. Paths are relative to the "phpdoc\htmlhelp" directory. Be sure, not to give any directory or file names with spaces in them. */ /* This must be a valid language code used in the phpdoc repository. Defaults to en. */ $LANGUAGE = 'en'; /* This must be the path including the executable file's name of the hhc.exe included in Microsoft HTML Help Workshop. The default is 'c:\\progra~1\\_development\\htmlhe~1\\hhc.exe'. */ $HELP_WORKSHOP = 'c:\\progra~1\\_development\\htmlhe~1\\hhc.exe'; /* This must be the directory, where the XSL generated HTML files and hh[pkc] supplemental files can be found. The defaults is 'html', the html output dir used by HTMLHelp XSL style sheets. */ $HTML_SRC = 'html'; /* This is the directory, where the files generated by this system should go. The default is 'htmlout'. Beware, that if you set this to the same as the above, the start cleanup will delete your source files (so you need to set $START_CLEANUP to FALSE in that case!) */ $HTML_TARGET = 'htmlout'; /* This must be a valid directory name, where the manual note sources can be found. The default is 'notesin' (a directory under "phpdoc\htmlhelp"). */ $NOTES_SRC = 'notesin'; /* This is the directory name, where the HTML files for the notes help file go. The default is 'notesout' (a directory under "phpdoc\htmlhelp"). It is created if nonexistent. */ $NOTES_TARGET = 'notesout'; /* This is the directory name, where all the release files will go. The default is 'release' (a directory under "phpdoc\htmlhelp"). It is created if nonexistent. */ $RELEASE_DIR = 'release'; /* This must be TRUE or FALSE, depending on whether you would like to use notes sources to build a "php_manual_notes.chm" output file or not. The default is to generate a note file. Note, that it is only safe to generate a notes file with the English version, as it has all the pages, while other translations don't have them, so using them as note bases would cause note data loss. */ $USE_NOTES = TRUE; /* This must be TRUE or FALSE, depending on whether you would like the script to do automatic cleanup on startup. The script cleans up all working directories, except $HTML_SRC, where the sources of this script are. This means that $HTML_TARGET, $NOTES_SRC, $NOTES_TARGET and $RELEASE_DIR folders are emptyed if this is TRUE. */ $START_CLEANUP = TRUE; /* Deletes all work files except the files in $RELEASE_DIR. This means that all the $HTML_SRC, $HTML_TARGET, $NOTES_SRC and $NOTES_TARGET directories are emptyed. You probably never want to do this, if you are developing the system, as all the HTML source files generated by "make" will be lost, and you need to start over again from make. */ $END_CLEANUP = FALSE; ?> Index: phpdoc/htmlhelp/make_chm.bat +++ phpdoc/htmlhelp/make_chm.bat @php -f make_chm.php Index: phpdoc/htmlhelp/make_chm.php +++ phpdoc/htmlhelp/make_chm.php <?php /* This is the main file of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. Written by Gabor Hojtsy <goba@php.net> Credits go to people worked on previous versions: Derick Rethans, Jirka Kosek, Thomas Schoefbeck and Harald Radi */ // Measure needed time $start_time = time(); // This script can take much time to run set_time_limit(0); // Include variables used by the build process // Test for local_vars, as they are not there by default if (!@file_exists("local_vars.php")) { die("ERROR: local_vars.php is needed, but not there"); } require_once "local_vars.php"; // Possible languages for manual generation $LANGUAGES = array( "cs", "de", "en", "es", "fr", "hu", "it", "ja", "kr", "nl", "pt_BR" ); echo " ____________________________________________________________ Generate Microsoft HTML Help document from the output of XSL generated HTML files of the PHP documentation. See \"local_vars.php.src\" for local parameter adjustment, see README.txt and the phpdoc howto for more information. ____________________________________________________________ "; // Process parameters echo "\n| Processing local parameters...\n"; if (!@is_dir($HTML_SRC)) { die("ERROR: HTML path not valid"); } if (!@file_exists($HELP_WORKSHOP)) { die("ERROR: HTML Workshop path not valid"); } if (!@is_dir($RELEASE_DIR)) { mkdir($RELEASE_DIR, 0700); echo "> $RELEASE_DIR directory created...\n"; } elseif ($START_CLEANUP) { echo "| Cleaning up $RELEASE_DIR directory...\n"; passthru("rmdir /S /Q $RELEASE_DIR"); mkdir($RELEASE_DIR, 0700); } if (!@is_dir($HTML_TARGET)) { mkdir($HTML_TARGET, 0700); echo "> $HTML_TARGET directory created...\n"; } elseif ($START_CLEANUP) { echo "| Cleaning up $HTML_TARGET directory...\n"; passthru("rmdir /S /Q $HTML_TARGET"); mkdir($HTML_TARGET, 0700); } if ($USE_NOTES) { if (!@is_dir($NOTES_SRC)) { mkdir($NOTES_SRC, 0700); echo "> $NOTES_SRC directory created...\n"; } elseif ($START_CLEANUP) { echo "| Cleaning up $NOTES_SRC directory...\n"; passthru("rmdir /S /Q $NOTES_SRC"); mkdir($NOTES_SRC, 0700); } if (!@is_dir($NOTES_TARGET)) { mkdir($NOTES_TARGET, 0700); echo "> $NOTES_TARGET directory created...\n"; } elseif ($START_CLEANUP) { echo "| Cleaning up $NOTES_TARGET directory...\n"; passthru("rmdir /S /Q $NOTES_TARGET"); mkdir($NOTES_TARGET, 0700); } echo "| php_manual_notes.chm target choosen...\n"; if ($LANGUAGE != 'en') { echo "| Warning: it is not safe to generate notes CHM for non-english HTML files\n"; } } // Test for mirror information file if (!file_exists("mirrors.inc")) { die("ERROR: Mirror information file (mirrors.inc) not found"); } // Generate files and compile echo "| Parameters processed... "; echo " > Now the HTML files are being filtered to make output as perfect as possible. Please be patient, as it can take some time... "; $counter = 0; require_once "filter_files.php"; echo "> $counter files are converted in previous step. "; if ($USE_NOTES) { $WITH_NOTES = $WITHOUT_NOTES = $NOTE_NUM = 0; echo " > Trying to split user notes 'all' file to separate directories and files (to make the next step fast and less resource intensive)... "; require_once "split_notes.php"; echo " > Now the user notes project file and HTML files are being created. Please be patient, as it can take as much time as the previous step... "; require_once "user_notes.php"; echo "> $WITH_NOTES files created with notes $WITHOUT_NOTES files found without notes Total number of notes: $NOTE_NUM "; } echo " > Now creating mirrors.ini file from current mirrors.inc... "; require_once "mirrors_ini.php"; echo " > Now starting HTML Help Workshop... ____________________________________________________________ "; // Run HTML Help Workshop, and move files to release directory passthru($HELP_WORKSHOP . " $HTML_TARGET\\php_manual_$LANGUAGE.hhp"); rename("$HTML_TARGET/php_manual_$LANGUAGE.chm", "$RELEASE_DIR/php_manual_$LANGUAGE.chm"); if ($USE_NOTES) { passthru($HELP_WORKSHOP . " $NOTES_TARGET\\php_manual_notes.hhp"); rename("$NOTES_TARGET/php_manual_notes.chm", "$RELEASE_DIR/php_manual_notes.chm"); } // Copy PHP manual preferences, qucikref and skins files to release directory // $RELEASE_DIR = str_replace("/", "\\", $RELEASE_DIR): exec("copy suppfiles\\prefs $RELEASE_DIR /Y"); exec("copy suppfiles\\quickref $RELEASE_DIR /Y"); exec("copy suppfiles\\fixes $RELEASE_DIR /Y"); exec("xcopy /S /I /Q suppfiles\\skins $RELEASE_DIR\\skins"); // Delete unused files if ($END_CLEANUP) { echo "> Removing every file except the release files...\n"; passthru("rmdir /S /Q $HTML_SRC"); passthru("rmdir /S /Q $HTML_TARGET"); passthru("rmdir /S /Q $NOTES_SRC"); passthru("rmdir /S /Q $NOTES_TARGET"); } // Measure time $alltime = time() - $start_time; echo "____________________________________________________________\n"; echo "Conversion done in " . ((int) ($alltime / 60)) . " minutes "; echo "and " . $alltime % 60 . " seconds.\n"; echo "You can find the generated file[s] in $RELEASE_DIR directory\n"; echo "____________________________________________________________\n"; ?> Index: phpdoc/htmlhelp/mirrors_ini.php +++ phpdoc/htmlhelp/mirrors_ini.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. This script generates mirrors.ini from mirrors.inc ( can be downloaded from http://MIRROR.php.net/include/mirrors.inc ) */ // Load the mirrors file in include_once "mirrors.inc"; // Get mirror site addresses $mirrors = array_keys($MIRRORS); // Write out mirror information $fp = fopen($RELEASE_DIR . "/mirrors.ini", "w"); fwrite($fp, "# ================================================= # PHP Manual CHM version mirror list configuration # ================================================= # Possible mirrors for online functions (only those # mirrors are listed, which were active when this # list was generated) [mirrors] "); // Write out all active mirror sites foreach ($MIRRORS as $mirror => $mirrrorinfo) { if ($mirrorinfo[7] == MIRROR_OK) { fwrite($fp, "mirror = \"$mirror\"\n"); } } fclose($fp); ?> Index: phpdoc/htmlhelp/README.txt +++ phpdoc/htmlhelp/README.txt Build system of the new CHMs ============================ [See latest "official" output package online at http://weblabor.hu/php-doc-chm] How to build a CHM manual with this system? 1. run "autoconf" in the phpdoc directory 2. run "./configure --with-chm=yes --with-xsl=yes" Optionally you may need to specify the "--with-xsltproc=path" option to explicitly provide the XSLTProc path. 3. Run "make chm_xsl" If xsltproc encounters errors in the XML files, correct the errors, commit them to phpdoc, and run "make chm_xsl" again. There is no need to reconfigure in most cases. After this step the HTML files to start are in phpdoc/htmlhelp/html 4. Get the actual mirrors.inc file from http://ANY_MIRROR.php.net/include/mirrors.inc and save into the directory where the make_chm.bat resides (overwrite old one if one exists). 6. Get all the user notes from http://ANY_MIRROR.php.net/backend/notes/ALL.bz2, extract it's contents, and place the resulting "all" file to the same folder where the make_chm.bat resides. 7. Copy local_vars.php.src to local_vars.php and adjust settings as needed. 8. Now run make_chm.bat Well, this is quite manual right now, and there are some problems need fixing (see the TODO.txt file too). Index: phpdoc/htmlhelp/split_notes.php +++ phpdoc/htmlhelp/split_notes.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. This code splits up the notes file to be easily processeable by the notes CHM generator script. */ // Check for previous run if (@is_dir("$NOTES_SRC/0")) { echo "\n> Previous user note split detected, skipping\n"; } // We have no splitted notes files, do it now else { // Open all notes source file for reading $fp = @fopen("all", "r"); if (!$fp) { die("ERROR: No all notes file present"); } // Read through the file, and write individual files while (!feof($fp)) { $line = chop(fgets($fp,8096)); if ($line == "") continue; // Get data from one line list($id,$sect,$rate,$ts,$user,$note) = explode("|",$line); $hash = substr(md5($sect),0,16); // Create dir if nonexistent if (!@is_dir("$NOTES_SRC/" . $hash[0])) { mkdir("$NOTES_SRC/" . $hash[0], 0700); } // Append line to appropriate file $nf = fopen("$NOTES_SRC/" . $hash[0] . "/$hash", "a"); fwrite($nf, $line . "\n"); fclose($nf); } // Close all notes file fclose($fp); } ?> Index: phpdoc/htmlhelp/TODO.txt +++ phpdoc/htmlhelp/TODO.txt ! Please contact goba@php.net before modifying ! the code in the "htmlhelp" folder in CVS. Important: - Add _function.html to the resulting CHM, which can redirect to a function page in the CHM. IDEs without direct PHP manual support can use this to integrate the CHM. - Make the build system support other languages then English. All the strings used need to be customizable. This also includes the porting of the charset conversion added lately to the "old chm" build system. - Make the build system run more automatically. Additional: - Do not clean up the notesin and notesout directories if recently generated files are there (the "all" file is older then those files generated there). - Also do not clean up the "htmlout" directory if the files there are newer then the ones in the "html" directory. - Implement some detection for the $HTML_SRC and $HTML_TARGET directories, and don't do cleanups, and some copying, if they are the same. - Experiment with Brendan Ferguson's JS syntax highlighter and test it's usage in user note coloring. This would make the resulting CHMs much smaller, but needs JS magic (may be slow). - Document the skin framework, how it works, so others will be able to create their own skins. Index: phpdoc/htmlhelp/user_notes.php +++ phpdoc/htmlhelp/user_notes.php <?php /* This file is part of the Windows Compiled HTML Help Manual Generator of the PHP Documentation project. The logic in this file comes from an extract of phpweb/include/shared-manual.inc and phpweb/include/layout.inc (clean_note()). From time to time, it may be needed to update the code, as the manual notes system changes. This file is consistent with: layout.inc - 1.66 shared-manual.inc - 1.125 This file also includes code to generate a project file for the notes. Grab the notes file (all compressed) from: http://ANY_MIRROR_SITE.php.net/backend/notes/all.bz2 */ // Check dependencies, die if error found if (!$USE_NOTES) { die("ERROR: User note generator called"); } // Merge all possible language manuals. Only the available // manual[s] will be active, while viewing $lang_chms = ''; foreach ($LANGUAGES as $code) { $lang_chms .= "php_manual_$code.chm\n"; } // We need a list of files for an IE6 workaround $NOTE_FILE_LIST = array(); // Start writing the notes project file $nproject = fopen("$NOTES_TARGET/php_manual_notes.hhp", "w"); fputs($nproject, "[OPTIONS] Compatibility=1.1 or later Compiled file=php_manual_notes.chm Default topic=_index.html Display compile progress=No Full-text search=Yes Language=0x0809 English (UNITED KINGDOM) Title=User Notes [MERGE FILES] $lang_chms [FILES] "); // Walk through all files in HTML_DIR directory $handle = opendir($HTML_SRC); while (false !== ($filename = readdir($handle))) { // Only process html files generated by XSL sheets if (strpos($filename, ".html") && (strpos($filename, "_") !== 0)) { // Get title (used for HTML page title) $content = join("", file("$HTML_SRC/$filename")); preg_match("!<title>([^<]+)</title>!Us", $content, $match); // Get user notes, or false on failure $user_notes = manualUserNotes($match[1], $filename); // If there are no user notes for this page, // no file will be generated, but if we generate // a file, we add it to project file too if ($user_notes != FALSE) { $WITH_NOTES++; $notes = fopen("$NOTES_TARGET/$filename", "w"); fwrite($notes, $user_notes); fclose($notes); fwrite($nproject, $filename . "\n"); $NOTE_FILE_LIST[] = $filename; echo "> $WITH_NOTES\r"; } else { $WITHOUT_NOTES++; } } } closedir($handle); // Copy note supplemental files, and add to file list copy("suppfiles/notes/_index.html", "$NOTES_TARGET/_index.html"); fwrite($nproject, "_index.html\n"); copy("suppfiles/notes/_style.css", "$NOTES_TARGET/_style.css"); fwrite($nproject, "_style.css\n"); // Write out a list of files to work around an IE6 bug $jsfile = fopen("$NOTES_TARGET/_filelist.js", "w"); fwrite($jsfile, "note_file_list = '" . join(" ", $NOTE_FILE_LIST) . "';\n\n"); fwrite($jsfile, "if (note_file_list.indexOf(chmfile_page) != -1) { notesIframe(); }"); fclose($jsfile); fwrite($nproject, "_filelist.js\n"); // Close ready project file fclose($nproject); // Make entry HTML fragment for a user note function makeEntry($date, $name, $blurb) { // Begin user notes header $entryhtml = "<div><p class=\"unheader\">\n"; // Get email/name of the user note writer $name = htmlspecialchars($name); if ($name && $name != "php-general@lists.php.net" && $name != "user@example.com") { if (ereg("(.+)@(.+)\.(.+)", $name)) { $entryhtml .= "<a href=\"mailto:$name\" class=\"useremail\"><span>$name</span></a>"; } else { $entryhtml .= "<b><span>$name</span></b>"; } } // Append date $entryhtml .= " (<span>" . date("d-M-Y h:i", $date) . "</span>)</p>\n"; // Append user note text, cleared $entryhtml .= "<p class=\"untext\"><tt><span>" . clean_note($blurb) . "</span></tt></p></div>\n"; // Return with entry HTML fragment return $entryhtml; } // Get user notes for this particular page, returns an array with notes function manualGetUserNotes($id) { global $NOTES_SRC, $NOTE_NUM; $notes = array(); $hash = substr(md5($id),0,16); $notes_file = "$NOTES_SRC/$hash[0]/$hash"; if ($fp = @fopen($notes_file,"r")) { while (!feof($fp)) { $line = chop(fgets($fp,8096)); if ($line == "") continue; list($id,$sect,$rate,$ts,$user,$note) = explode("|",$line); $notes[] = array( "id" => $id, "sect" => $sect, "rate" => $rate, "xwhen" => $ts, "user" => $user, "note" => base64_decode($note) ); } fclose($fp); } $NOTE_NUM += count($notes); return $notes; } // Get the HTML file for a user note page, or false on failure function manualUserNotes($title, $id) { // Don't want .html at the end of the ids if (substr($id,-5) == '.html') { $id = substr($id,0,-5); } // Get user notes $notes = manualGetUserNotes($id); // If we have no notes, do not produce useless HTML if (count($notes) == 0) { return FALSE; } // start HTML output $notehtml = <<<END_OF_MULTI <html> <head> <title>N: $title</title> <link rel="stylesheet" href="_style.css"> </head> <body onLoad="if(parent.nbuff) {parent.displayNotes()}"> <h3>User contributed notes:</h3> END_OF_MULTI; // Go through manual notes, and make entries foreach ($notes as $note) { $notehtml .= makeEntry($note['xwhen'], $note['user'], $note['note'], $note['id']); } // Be good guys, and end HTML code here $notehtml .= "\n</body></html>"; // Return with manual notes for this page return $notehtml; } // Clean note to get right display function clean_note($text) { // Do not allow people to fool the system with bogus HTML $text = htmlspecialchars(trim($text)); // turn urls into links $text = preg_replace("/((mailto|http|ftp|nntp|news):.+?)(>|\\s|\\)|\"|\\.\\s|$)/","<a href=\"\\1\">\\1</a>\\3",$text); // this 'fixing' code will go away eventually $fixes = array('<br>','<p>','</p>'); reset($fixes); while (list(,$f)=each($fixes)) { $text=str_replace(htmlspecialchars($f), $f, $text); $text=str_replace(htmlspecialchars(strtoupper($f)), $f, $text); } // Allow only one <br> (drop out long empty sections) $text = preg_replace("!(<br>\\s*)+!", "<br>", $text); // wordwrap is not applicable here, because (it is buggy and) // we need to make text break as window resized // Convert new lines in notes to <br> / <br /> $text = nl2br(preg_replace("![\\n\\r]+!", "\n", $text)); // Get files to smaller size (bad hack :) $text = str_replace("<br />", "<br>", $text); // We do not use <pre> but would like to see indentation $text = str_replace(" ", " ", $text); // Paras cannot be used here, replace with <br><br> $text = str_replace("<p>", "<br><br>", $text); // Drop out end of paras $text = str_replace("</p>", "", $text); return $text; } ?>