Rev 543 Rev 545
Line 1... Line 1...
1 <?php 1 <?php
2 // This PHP script generates clickable HTML documentation files for amforth 2 // This PHP script generates clickable HTML documentation files for amforth
3 // project. Script should be run once (offline) when new versions of sorces are 3 // project. Script should be run once (offline) when new versions of sorces are
4 // available. It creates new subdirectory with HTML documentation tree. 4 // available. It creates new subdirectory with HTML documentation tree.
5 // 5 //
6 // Configuration file is GenerateHTML.cfg 6 // Default configuration is in file GenerateHTML.cfg
-   7 //
-   8 // Command Line paramaters are available via php GenerateHTML.php --help
7 // 9 //
8 // (c)miho 2007 / http://www.mlab.cz 10 // (c)miho 2007 / http://www.mlab.cz
9   11  
10 // ********************************************************************** 12 // **********************************************************************
11 // History 13 // History
12 // ********************************************************************** 14 // **********************************************************************
13 // 0.00 work wersion 15 // 0.00 work wersion
-   16 // 0.01 basic functionality
14   17  
15   18  
16 // ********************************************************************** 19 // **********************************************************************
17 // Definitions/parameters 20 // Definitions/parameters
18 // ********************************************************************** 21 // **********************************************************************
Line 28... Line 31...
28 // ********************************************************************** 31 // **********************************************************************
29 // Generic Funcions 32 // Generic Funcions
30 // ********************************************************************** 33 // **********************************************************************
31   34  
32   35  
-   36 function Error($ErrorStr)
-   37 // If ErrorStr is not empty print it and die
-   38 {
-   39 if ($ErrorStr=="")
-   40 return;
-   41 print "\n";
-   42 print " ERROR: -->".$ErrorStr."\n";
-   43 die(1);
-   44 }
-   45  
-   46  
33 function MyReadFile($FileName, &$FileContent) 47 function MyReadFile($FileName, &$FileContent)
34 // Reads file, returns file as a single string 48 // Reads file, returns file as a single string
35 { 49 {
-   50 //
-   51 if ($FileName=="")
-   52 return "No File Name";
-   53  
36 // Read file 54 // Read file
37 $FileContent=@file($FileName); 55 $FileContent=@file($FileName);
38   56  
39 // Test if file contains any content 57 // Test if file contains any content
40 if ($FileContent==FALSE) 58 if ($FileContent==FALSE)
41 { -  
42 unset($FileContent); -  
43 return "No Data in File $FileName"; 59 return "No Data in File: $FileName";
44 } -  
45   60  
46 // Remove CR or LF or CR/LF 61 // Remove CR or LF or CR/LF
47 foreach($FileContent as $Key => $Line) 62 foreach($FileContent as $Key => $Line)
48 { 63 {
49 $FileContent[$Key]=rtrim($Line); 64 $FileContent[$Key]=rtrim($Line);
Line 132... Line 147...
132 // ********************************************************************** 147 // **********************************************************************
133 // Function for processing 148 // Function for processing
134 // ********************************************************************** 149 // **********************************************************************
135   150  
136   151  
-   152 function Help()
-   153 // Display help
-   154 {
-   155 print "\n";
-   156 print "This script takes default parameters from GenerateHTML.cfg.\n";
-   157 print "\n";
-   158 print "Parameters can be entered directly on command line as well:\n";
-   159 print " php GenerateHTML.php par1=val1 par2=val2\n";
-   160 print "\n";
-   161 print "Sometimes (in Windows) it is necessary to use quotation marks this way:\n";
-   162 print " php GenerateHTML.php \"par1=val1\" \"par2=val2\"\n";
-   163 print "\n";
-   164 print "Parameters are: \n";
-   165 print " EnableApache={0|1} - Enable to run in Apache\n";
-   166 print " SourceDir=path - path to asm source directory\n";
-   167 print " SourceAsm=file - name of top level asm source file\n";
-   168 print " TemplateDir=path - path to HTML template\n";
-   169 print " DestinationDir=path - path to destination HTML\n";
-   170 Error("\n");
-   171 }
-   172  
-   173  
-   174 function Parameters(&$CFG)
-   175 // Function process Command Line parameters
-   176 {
-   177 // Info
-   178 print "Parameters\n";
-   179 // Dummy values
-   180 $CFG["EnableApache"] = 0; // Do not allow run in Apache
-   181 $CFG["SourceDir"] = "";
-   182 $CFG["SourceAsm"] = "";
-   183 $CFG["TemplateDir"] = "";
-   184 $CFG["DestinationDir"] = "";
-   185 // Default values (in cfg file)
-   186 @include_once("GenerateHTML.cfg");
-   187 // Command Line parameters
-   188 if ($_SERVER["argc"]>1)
-   189 {
-   190 // Help
-   191 if ($_SERVER["argv"][1]=="--help")
-   192 Help();
-   193 // Drop
-   194 unset($_SERVER["argv"][0]);
-   195 // Go through arguments
-   196 foreach($_SERVER["argv"] as $Key => $Value)
-   197 {
-   198 $Left=substr($Value,0,strpos($Value,"="));
-   199 $Right=substr($Value,strpos($Value,"=")+1);
-   200 if (isset($CFG[$Left]) && $Right!="" )
-   201 {
-   202 $CFG[$Left]=$Right;
-   203 }
-   204 else
-   205 {
-   206 return "Invalid Parameter: $Value";
-   207 }
-   208 }
-   209 }
-   210  
-   211 // Correct paths and existence
-   212 foreach($CFG as $Key => $Value)
-   213 {
-   214 if (stripos($Key,"Dir"))
-   215 {
-   216 // Correct / at the end of path
-   217 if (substr($Value,strlen($Value)-1)!="/")
-   218 {
-   219 $CFG[$Key]=$Value."/";
-   220 }
-   221 // Check existence
-   222 #print "DIR".$CFG[$Key]."\n";
-   223 if ( ! is_dir($CFG[$Key]))
-   224 {
-   225 return "Directory does not exist: ".$Key."=".$CFG[$Key];
-   226 }
-   227 }
-   228 }
-   229  
-   230 // Print info
-   231 if (count(CFG))
-   232 foreach($CFG as $Key => $Value)
-   233 print " $Key=$Value\n";
-   234 print "\n";
-   235  
-   236 // Check if alowed to run in Apache
-   237 if ($_SERVER["argc"]==0 & ! $CFG["Apache"])
-   238 return "This Script is configured so that it will not run in Apache.";
-   239  
-   240 // No Error
-   241 return "";
-   242 }
-   243  
-   244  
137 function SourceAsm($SourceDir, $FileName, &$SourceAsmFiles, &$LabelList ) 245 function SourceAsm($SourceDir, $FileName, &$SourceAsmFiles, &$LabelList )
138 // Process ASM source file, recurse all includes 246 // Process ASM source file, recurse all includes
-   247 // Returns Error String
139 // Stores file names and labels into two arrays 248 // Stores file names and labels into two arrays
140 // IN $SourceDir - base directory (not printed) 249 // IN $SourceDir - base directory (not printed)
141 // IN $FileName - file to process 250 // IN $FileName - file to process
142 // OUT $SourceAsmFiles - list of all processed files (Filename) 251 // OUT $SourceAsmFiles - list of all processed files (Filename)
143 // OUT $LabelList - list of all labels (Label, FileName, LineNumber) 252 // OUT $LabelList - list of all labels (Label, FileName, LineNumber)
Line 147... Line 256...
147 print "Read Asm: $FileName\n"; 256 print "Read Asm: $FileName\n";
148   257  
149 // Read file 258 // Read file
150 $Error=MyReadFile($SourceDir.$FileName, $FileContent); 259 $Error=MyReadFile($SourceDir.$FileName, $FileContent);
151 if ($Error!="") 260 if ($Error!="")
152 { -  
153 print $Error."\n"; -  
154 return 1; 261 return $Error;
155 } -  
156 262  
157 // Remember filename 263 // Remember filename
158 $SourceAsmFiles[]=$FileName; 264 $SourceAsmFiles[]=$FileName;
159   265  
160 // Filter source file line by line - find labels 266 // Filter source file line by line - find labels
161 foreach($FileContent as $Key => $Value) 267 foreach($FileContent as $Key => $Value)
Line 191... Line 297...
191 $Dir=dirname($FileName)."/"; 297 $Dir=dirname($FileName)."/";
192 if ($Dir=="./") 298 if ($Dir=="./")
193 { 299 {
194 $Dir=""; 300 $Dir="";
195 } 301 }
196 SourceAsm($SourceDir, $Dir.$Value, $SourceAsmFiles, $LabelList); 302 $Error=SourceAsm($SourceDir, $Dir.$Value, $SourceAsmFiles, $LabelList);
-   303 if ($Error!="")
-   304 return $Error;
197 } 305 }
198 unset($Includes); 306 unset($Includes);
199 } 307 }
200   308  
201 // End 309 // End
202 return 0; 310 return "";
203 } 311 }
204   312  
205   313  
206 function PrintSourceAsm(&$SourceAsmFiles) 314 function PrintSourceAsm(&$SourceAsmFiles)
207 // Prints all procesed ASM files 315 // Prints all procesed ASM files
208 { 316 {
209 print "Asm Source File List\n"; 317 print "Asm Source File List\n";
-   318 if (count($SourceAsmFiles))
210 foreach($SourceAsmFiles as $Key => $Value) 319 foreach($SourceAsmFiles as $Key => $Value)
211 { 320 {
212 print " ".$Value."\n"; 321 print " ".$Value."\n";
213 } 322 }
214 print "\n"; 323 print "\n";
Line 217... Line 326...
217   326  
218 function PrintLabels(&$LabelList) 327 function PrintLabels(&$LabelList)
219 // Prints all found labels 328 // Prints all found labels
220 { 329 {
221 print "Label List\n"; 330 print "Label List\n";
-   331 if (count($LabelList))
222 foreach($LabelList as $Key => $Value) 332 foreach($LabelList as $Key => $Value)
223 { 333 {
224 print " ".$Value["Label"]." ".$Value["FileName"]." ".$Value["LineNumber"]."\n"; 334 print " ".$Value["Label"]." ".$Value["FileName"]." ".$Value["LineNumber"]."\n";
225 } 335 }
226 print "\n"; 336 print "\n";
227 } 337 }
228   338  
229   339  
230 function CreateWordList($SourceDir, &$LabelList, &$WordList) 340 function CreateWordList($SourceDir, &$LabelList, &$WordList)
231 // Goes through LabelList and looks for word definitions 341 // Goes through LabelList and looks for word definitions
-   342 // Returns Error String
232 // IN $LabelList - Found labels 343 // IN $LabelList - Found labels
233 // OUT $WordList - Word List (ShortLabel, Word, Comment, Label, FileName) 344 // OUT $WordList - Word List (ShortLabel, Word, Comment, Label, FileName)
234 { 345 {
235   346  
236 print "Word List\n"; 347 print "Word List\n";
237 348
238 if ($LabelList) 349 if (count($LabelList))
239 foreach ($LabelList as $Value) 350 foreach ($LabelList as $Value)
240 { 351 {
241 // Take all VE definitions 352 // Take all VE definitions
242 if (stristr(substr($Value["Label"],0,3),"VE_")) 353 if (stristr(substr($Value["Label"],0,3),"VE_"))
243 { 354 {
Line 250... Line 361...
250   361  
251 // Read source file 362 // Read source file
252 $FileName=$SourceDir.$Value["FileName"]; 363 $FileName=$SourceDir.$Value["FileName"];
253 $Error=MyReadFileString($FileName, $FileContent); 364 $Error=MyReadFileString($FileName, $FileContent);
254 if ($Error!="") 365 if ($Error!="")
255 { -  
256 print " ".$Error."\n"; -  
257 return 1; 366 return $Error;
258 } -  
259 $FileContent="\n".$FileContent; 367 $FileContent="\n".$FileContent;
260 368
261 // Find label 369 // Find label
262 if (preg_match($Pattern,$FileContent,$Matches)) 370 if (preg_match($Pattern,$FileContent,$Matches))
263 { 371 {
Line 314... Line 422...
314 // Clean Up 422 // Clean Up
315 unset($FileContent); 423 unset($FileContent);
316 } 424 }
317 } 425 }
318 print "\n"; 426 print "\n";
-   427 return "";
319 } 428 }
320   429  
321   430  
322 function GenerateWordList($TemplateDir, $DestinationDir, &$LabelList, &$WordList) 431 function GenerateWordList($TemplateDir, $DestinationDir, &$LabelList, &$WordList)
323 // Creates HTML pages with Word List 432 // Creates HTML pages with Word List
-   433 // Returns Error String
324 // IN $TemplateDir - template directory (file WordList.*.html) 434 // IN $TemplateDir - template directory (file WordList.*.html)
325 // IN $LabelList - list of labels (Label, FileName, LineNumber) 435 // IN $LabelList - list of labels (Label, FileName, LineNumber)
326 // IN $WordList - list of words (ShortLabel, Word, Comment, Label, FileName) 436 // IN $WordList - list of words (ShortLabel, Word, Comment, Label, FileName)
327 // OUT WordList.*.html - create HTML pages (file WordList.*.html) 437 // OUT WordList.*.html - create HTML pages (file WordList.*.html)
328 { 438 {
329 // Find all templates 439 // Find all templates
330 print "Word List in HTML\n"; 440 print "Word List in HTML\n";
-   441 if (count(glob($TemplateDir."WordList.*.html")))
331 foreach (glob($TemplateDir."WordList.*.html") as $FileName) 442 foreach (glob($TemplateDir."WordList.*.html") as $FileName)
332 { 443 {
333 // Process template file 444 // Process template file
334 print " Temlate $FileName\n"; 445 print " Temlate $FileName\n";
335   446  
336 // Read template file 447 // Read template file
337 $Error=MyReadFileString($FileName, $FileContent); 448 $Error=MyReadFileString($FileName, $FileContent);
338 if ($Error!="") 449 if ($Error!="")
339 { -  
340 print " ".$Error."\n"; -  
341 return 1; 450 return $Error;
342 } -  
343   451  
344 // Find <<WordList>> 452 // Find <<WordList>>
345 if (!preg_match("/( *)(<<WordList>>)/i",$FileContent,$Matches)) 453 if (!preg_match("/( *)(<<WordList>>)/i",$FileContent,$Matches))
346 { 454 {
347 print " Missing <<WordList>> in template file\n"; -  
348 unset($FileContent); 455 unset($FileContent);
349 return -1; 456 return "Missing <<WordList>> in template file";
350 } 457 }
351 $Indent=$Matches[1]; 458 $Indent=$Matches[1];
352 459
353 // Create HTML code - table header 460 // Create HTML code - table header
354 $WordListHTML[]="<table>"; 461 $WordListHTML[]="<table>";
Line 357... Line 464...
357 $WordListHTML[]=" <th>Label</th>"; 464 $WordListHTML[]=" <th>Label</th>";
358 $WordListHTML[]=" <th>Definition</th>"; 465 $WordListHTML[]=" <th>Definition</th>";
359 $WordListHTML[]=" </tr>"; 466 $WordListHTML[]=" </tr>";
360 467
361 // Create HTML code - table lines 468 // Create HTML code - table lines
-   469 if (count($WordList))
362 foreach($WordList as $Key => $Value) 470 foreach($WordList as $Key => $Value)
363 { 471 {
364 // Prepare (just for readibility) 472 // Prepare (just for readibility)
365 $Word=$Value["Word"]; 473 $Word=$Value["Word"];
366 $Link="<a href=\"".ASMFILES.FileName2HTML($Value["FileName"])."#".$Value["ShortLabel"]. 474 $Link="<a href=\"".ASMFILES.FileName2HTML($Value["FileName"])."#".$Value["ShortLabel"].
Line 388... Line 496...
388 #print $FileContent; 496 #print $FileContent;
389 497
390 // Create Output File 498 // Create Output File
391 $Error=MyWriteFile($DestinationDir.basename($FileName), $FileContent); 499 $Error=MyWriteFile($DestinationDir.basename($FileName), $FileContent);
392 if ($Error!="") 500 if ($Error!="")
393 { -  
394 print " ".$Error."\n"; -  
395 return -1; 501 return $Error;
396 } -  
397   502  
398 // Clear memory 503 // Clear memory
399 unset($FileContent); 504 unset($FileContent);
400 unset($WordListHTML); 505 unset($WordListHTML);
401 } 506 }
402   507  
403 // Delimiter 508 // Delimiter
404 print "\n"; 509 print "\n";
-   510 return "";
405 } 511 }
406   512  
407   513  
408 function GenerateAsmFiles($TemplateDir, $SourceDir, &$SourceAsmFiles, $DestinationDir) 514 function GenerateAsmFiles($TemplateDir, $SourceDir, &$SourceAsmFiles, $DestinationDir)
409 // Cretaes HTML files from all processed ASM files 515 // Cretaes HTML files from all processed ASM files
410 // IN 516 // Returns Error String
-   517 // IN $TemplateDir - directory with template files
-   518 // IN $SourceDir - directory with asm source files
411 // 519 // OUT $SourceAsmFiles -
-   520 // IN $DestinationDir - directory for generated HTML files
412 { 521 {
413 // Info 522 // Info
414 print "Copy ASM Files\n"; 523 print "Copy ASM Files\n";
415   524  
416 // Destination directory exists 525 // Destination directory exists
417 $DestinationDir.=ASMFILES; 526 $DestinationDir.=ASMFILES;
418 if (!is_dir($DestinationDir)) 527 if (!is_dir($DestinationDir))
419 { -  
420 if (!@mkdir($DestinationDir)) 528 if (!@mkdir($DestinationDir))
421 { -  
422 print " Unable Create Dir ".$DestinationDir."\n"; 529 return "Unable Create Dir ".$DestinationDir;
423 return -1; -  
424 } -  
425 } -  
426 530  
427 // Read template 531 // Read template
428 $Error=MyReadFileString($TemplateDir."FileAsm.en.html", $Template); 532 $Error=MyReadFileString($TemplateDir."FileAsm.en.html", $Template);
429 if ($Error!="") 533 if ($Error!="")
430 { -  
431 print " ".$Error."\n"; -  
432 return -1; 534 return $Error;
433 } -  
434   535  
435 // Copy all source files 536 // Copy all source files
436 foreach($SourceAsmFiles as $Key => $FileName) 537 foreach($SourceAsmFiles as $Key => $FileName)
437 { 538 {
438 print " ".$FileName."\n"; 539 print " ".$FileName."\n";
439   540  
440 // Read ASM file 541 // Read ASM file
441 $Error=MyReadFileString($SourceDir.$FileName, $FileContent); 542 $Error=MyReadFileString($SourceDir.$FileName, $FileContent);
442 if ($Error!="") 543 if ($Error!="")
443 { -  
444 print " ".$Error."\n"; -  
445 return 1; 544 return $Error;
446 } -  
447   545  
448 // Prepare HTML 546 // Prepare HTML
449 $FileContent=htmlspecialchars($FileContent); 547 $FileContent=htmlspecialchars($FileContent);
450 $FileContent="<pre>\n".$FileContent."\n</pre>"; 548 $FileContent="<pre>\n".$FileContent."\n</pre>";
451   549  
Line 455... Line 553...
455 $TemplateWork=str_ireplace("<<FileContent>>", $FileContent, $TemplateWork); 553 $TemplateWork=str_ireplace("<<FileContent>>", $FileContent, $TemplateWork);
456   554  
457 // Write ASM file in HTML 555 // Write ASM file in HTML
458 $Error=MyWriteFile($DestinationDir.FileName2HTML($FileName), $TemplateWork); 556 $Error=MyWriteFile($DestinationDir.FileName2HTML($FileName), $TemplateWork);
459 if ($Error!="") 557 if ($Error!="")
460 { -  
461 print " ".$Error."\n"; -  
462 return -1; 558 return $Error;
463 } -  
464 } 559 }
465 560
466 // Delimiter 561 // Delimiter
467 print "\n"; 562 print "\n";
-   563 return "";
468 } 564 }
469   565  
470   566  
471 // ********************************************************************** 567 // **********************************************************************
472 // Main Block 568 // Main Block
473 // ********************************************************************** 569 // **********************************************************************
474   570  
-   571 // Global Like Variables (arrays)
-   572 // $CFG - Config parameters
-   573 // $SourceAsmFiles - All processed ASM files (filenames)
-   574 // $LabelList - All label definitions (Label, FileName, LineNumber)
-   575 // $WordList - Word List (ShortLabel, Word, Comment, Label, FileName)
475   576  
476 // This file contains configurations for this script 577 // Process Command Line Parameters
477 require_once("GenerateHTML.cfg"); -  
478   -  
479   -  
480 // Global Like Variables 578 Error(Parameters($CFG));
481 //$SourceAsmFiles - All processed ASM files (filenames) -  
482 //$LabelList - All label definitions (Label, FileName, LineNumber) -  
483 //$WordList - Word List (ShortLabel, Word, Comment, Label, FileName) -  
484   -  
485   579  
486 // Process all ASM files from the root level 580 // Process all ASM files from the root level
487 SourceAsm($CFG_SourceDir, $CFG_SourceAsm, $SourceAsmFiles, $LabelList); 581 Error(SourceAsm($CFG["SourceDir"], $CFG["SourceAsm"], $SourceAsmFiles, $LabelList));
488 PrintSourceAsm($SourceAsmFiles); 582 PrintSourceAsm($SourceAsmFiles);
489 PrintLabels($LabelList); 583 PrintLabels($LabelList);
490   584  
491 // Destilate Labels and Words 585 // Destilate Labels and Words
492 CreateWordList($CFG_SourceDir, $LabelList, $WordList); 586 Error(CreateWordList($CFG["SourceDir"], $LabelList, $WordList));
493   587  
494 // Create HTML WordList 588 // Create HTML WordList
495 GenerateWordList($CFG_TemplateDir, $CFG_DestinationDir, $LabelList, $WordList); 589 Error(GenerateWordList($CFG["TemplateDir"], $CFG["DestinationDir"], $LabelList, $WordList));
496   590  
497 // Copy ASM files and convert them into HTML 591 // Copy ASM files and convert them into HTML
498 GenerateAsmFiles($CFG_TemplateDir, $CFG_SourceDir, $SourceAsmFiles, $CFG_DestinationDir); 592 Error(GenerateAsmFiles($CFG["TemplateDir"], $CFG["SourceDir"], $SourceAsmFiles, $CFG["DestinationDir"]));
499   593  
-   594 // Finish
-   595 print "O.K.\n";
-   596 return
500   597  
501 // Zpracování readme autora + verze 598 // Zpracování readme autora + verze
502 // Dodělat kontroly vstupní CFG parametrů (existence souborů a adresářů) -  
503 // Osetreni chyb - die(1) zpusobi chybu (v shellu a da se tak poznat, ze to nedopadlo) -  
504   -  
505 // Zpracování templejtů do samostatného podprogramu (vyřešit indent...) 599 // Zpracování templejtů do samostatného podprogramu (vyřešit indent...)
506 // tím se vyřeší i en/cs verze Asm souboru 600 // tím se vyřeší i en/cs verze Asm souboru
507   -  
508 // Generovat log do souboru místo printu (zvážit) oddělit chyby a varování 601 // Generovat log do souboru místo printu (zvážit) oddělit chyby a varování
509 // Vyčistit cílový adresář 602 // Vyčistit cílový adresář
510 // Process all FORTH files 603 // Process all FORTH files
511 // Problém s rekurzí (potenciální nekonečno) 604 // Problém s rekurzí (potenciální nekonečno)
512 // Chtělo by to do stránek vkládat info o verzi a (c) 605 // Chtělo by to do stránek vkládat info o verzi a (c)