[prev in list] [next in list] [prev in thread] [next in thread]
List: quanta
Subject: Re: [Quanta] updating documentation for php, javascript, css
From: Eric Laffoon <sequitur () kde ! org>
Date: 2006-08-27 19:48:57
Message-ID: 200608271248.58021.sequitur () kde ! org
[Download RAW message or body]
On Sunday 27 August 2006 9:43 am, anthony@chovy.com wrote:
> I noticed php5 isn't well documented.
You mean in Quanta? I can't do much about the rest. I wrote a PHP script to
take the PHP documentation from CVS and make DTEP tag files. I just realized
my PHP CLI is broken and I have a lot of system upgrades to do. I'll attach
the file. It may help with creating docs too. Last time I used it I believe
it did a pretty good job, but the problem with PHP docs is the
inconsistencies in how it is structured. It hasn't been as clean as KDE
DocBook for instance.
>
> Also, when I went to download more documentation, I somehow ended up
> with two of everything in the menu.
It's possible it's reading both root and local trees and there are duplicates.
Usually when this happens local supercedes root.
--
Eric Laffoon - Quanta+ Team Leader
http://quanta.kdewebdev.org
["phpcvsdoc2tag.php" (application/x-php)]
#!/usr/bin/php
<?php
/** PHP tag file generation script for Quanta Plus - should work on PHP4
* This requires the PHP DocBook manual from their CVS
* File framework created by Robert Nickel robert@artnickel.com
* File completed by Eric Laffoon sequitur@kde.org
* This file is licensed GPL-2
* last updated $Id: Exp $
*/
/*-------- Setup To your system configuration -----------------------*/
$debug = 1; //0==off, 1==on; 2==verbose
$add_new_comments = false; //use the $add_comment_file - see comments below
$overwrite_comments = false; // set to true if you want to overwrite existing \
comments $homedir="/home/eric";
$kwddir="$homedir/kdecvs"; //where kdewebdev is located
$basepath="$homedir/kdecvs/phpdoc"; //php cvs docs directory
$docpath="$basepath/en/reference";
$versionfile="$basepath/xsl/version.xml";
$cmtpath="$kwddir/kdewebdev/quanta/data/dtep/php"; //where dtep with comments is
$outpath="$kwddir/kdewebdev/quanta/data/dtep/php";
$add_new_comments_file="$homedir/phpcomments.php";//this is a PHP file!
//$outpath="/home/eric/tmp/dtep";
$versiondata = getVersions($versionfile);
/** read in any comments written into the DTEP tags
* comments are added as $dtep_comment['tagname']=>'comment'
* commenting a number of tags can be done using the $add_new_comments_file.
* to use the $add_new_comments_file create the populated $dtep_comment array
<?
$dtep_comment = array('tag1'=>'comment1','tag2'=>'comment2',...);
?>
* SET $add_new_comments TO 0 IMMEDIATELY AFTER!
* I have not bothered to check the existance of the file either.
*/
if(!$add_new_comments)
$dtep_comment = array(); //only use comments already in DTEP
else
include($add_new_comments_file); //create the comment array with new comments
$pfh=popen("ls $cmtpath/*.tag","r");
while(!feof($pfh)) {
$fnm=ltrim(rtrim(fgets($pfh)));
if($fnm!="") {
if ($debug)
print "Reading DTEP file $fnm\n";
parse_tag($fnm);
}
}
pclose($dfh);
/*------- Process the PHP doc files to create the tag files ---------*/
$dfh=popen("find $docpath/ -type d -maxdepth 2 | grep functions","r");
while(!feof($dfh)) {
$dirnam=ltrim(rtrim(fgets($dfh)));
if ($debug)
print "$dirnam\n";
if($dirnam!="") {
$filenameout = $outpath."/".substr($dirnam,strlen($docpath),strpos($dirnam,"/functions")-strlen($docpath)).".tag";
$pfh=popen("ls $dirnam/*.xml","r");
$filedata = "<!DOCTYPE tags>\n<tags>\n";
while(!feof($pfh)) {
$fnm=ltrim(rtrim(fgets($pfh)));
if($fnm!="") {
if ($debug)
print "Reading file $fnm\n";
// print "=====================================================\n";
$fileret .= parse_file($fnm);
if($fileret)
$filedata .= parse_file($fnm);
// print "=====================================================\n";
}
}
$filedata .= "</tags>";
pclose($pfh);
//write the file
$handle = fopen($filenameout,w);
if(!fwrite($handle,$filedata))
die("unable to write file $filenameout");
fclose($handle);
}
}
pclose($dfh);
if ($debug)
var_dump($dtep_comment); //dump comment block
exit(0);
/** Collecting tagfile comments
* RULES as this code is written
1) all lines containing the tag name and comment must NOT contain line breaks
2) comments may NOT contain double quotes -> "
*/
function parse_tag($fname) {
global $debug, $dtep_comment, $overwrite_comments;
if(rtrim($fname)=="") return false; //bail on bad file
$ifh=fopen($fname,"r");
if(!$ifh) return false;
$done=false;
while(!feof($ifh) && !$done) {
$buf = ltrim(fgets($ifh));
if(substr($buf,0,10) == "<tag name=") { //tag open
$cs = strpos($buf,"comment=");
if($cs) {//has comment - read tag
$tagname = substr($buf,11,strpos($buf,'"',11)-11);
if(!(array_key_exists($tagname,$dtep_comment) && $overwrite_comments)) {
$cs += 9;
$comment = substr($buf,$cs,strpos($buf,'"',$cs)-$cs);
$dtep_comment[$tagname] = $comment;
}
}
}
}
}
function parse_file($fname) {
global $debug, $versiondata;
//$ifh=fopen("/home/robertcn/cvs/phpdoc/en/reference/datetime/functions/date.xml","r");
if(rtrim($fname)=="") return false; //bail on bad file
$ifh=fopen($fname,"r");
if(!$ifh) return false;
$done=false;
while(!feof($ifh) && !$done) {
$buf=ereg_replace("^ *","",fgets($ifh));
$buf=rtrim($buf); //gack trailing spaces if any
//Let's parse until we find the methodsynopsis opening tag
if(ereg("<methodsynopsis>",$buf)) {
$parser=$buf;
$endblock=false;
while(!feof($ifh) && !$endblock) {
$buf=ereg_replace("^ *","",fgets($ifh));
$buf=rtrim($buf); //gack trailing spaces if any
// $buf=ereg_replace("><",">\n<",$buf);
if(ereg("</methodsynopsis>",$buf)) $endblock=true;
$parser.=$buf;
}
$done=true;
} //if(method...
}
fclose($ifh);
if($done) {
//print "Before:\n$parser\n";
//print "--\n";
$parser=ereg_replace("(</?[^>]*>)","\\1\n",$parser);
$parser=ereg_replace("(\n[^<]+)","\\1\n",$parser);
$parser=ereg_replace("\n+$","",$parser);
//print "After:\n$parser\n";
//print "----------------------------------------\n";
$pary=explode("\n",$parser);
if ($debug > 1)
print_r($pary);
$fmted = format_data($pary);
}
return $fmted;
}
function format_data($pary) {
global $versiondata, $dtep_comment;
if($dtep_comment[$pary[5]])
$comment = " comment=\"".$dtep_comment[$pary[5]]."\"";
else
$comment = "";
$strout = "\t<tag name=\"$pary[5]\" type=\"function\" returnType=\"$pary[2]\" \
version=\"".$versiondata[$pary[5]]."\"$comment>\n"; $meth = 0;
for ($i=7;$i<=count($pary);$i++) {
if ($flag == "parm")
$attrname = $pary[$i];
if ($flag == "type")
$atttype = $pary[$i];
switch ($pary[$i]) {
case "<methodparam>":
$opt = ' status="required"';
$meth++;
break;
case "<type>":
$flag = "type";
break;
case "<parameter>":
$flag = "parm";
break;
case '<methodparam choice="opt">':
$opt = ' status="optional"';
$meth++;
break;
case "</methodparam>":
$strout .= "\t\t<attr name=\"$attrname\" type=\"$atttype\"$opt></attr>\n";
unset ($flag,$attrname,$atttype);
$meth = 0;
break;
default:
if (substr($pary[$i],0,10) == "<parameter") //odd <parameter role="reference"> \
or other $flag = "parm";
else
unset ($flag);
}
}
$strout .= "\t</tag>\n";
return $strout;
}
function getVersions ($readfile) {
$versions = array();
$handle = fopen($readfile, "r");
while (!feof($handle)) {
$buffer = ltrim(fgets($handle));
$startfunc = 16; // <function name="
if ($startfunc) {
$endfunc = strpos($buffer,'"',$startfunc+1);
$startversion = strpos($buffer,'"',$endfunc+1)+1;
$endversion = strpos($buffer,'"',$startversion+1);
$funcname = substr($buffer,$startfunc,$endfunc-$startfunc);
$version = substr($buffer,$startversion,$endversion-$startversion);
$versions[$funcname] = $version;
}
}
fclose($handle);
return $versions;
}
/*********************************************************************
XML tags found inside of the various methodsynopsis areas
**********************************************************************
<methodsynopsis>
<type> </type> --required
<methodname></methodname> --required
<methodparam[ choice="opt" | rep="repeat"]> --optional
<type></type> --required \
inside here
<parameter></parameter> --optional
<parameter/> --optional \
form for no parameters/synonym for void/ tag. </methodparam>
<void/>|<void /> -- ( void )
</methodsynopsis>
*********************************************************************/
?>
_______________________________________________
Quanta mailing list
Quanta@mail.kde.org
https://mail.kde.org/mailman/listinfo/quanta
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic