Re: Package Proposal: Tools and Utilities: PDS

Alan Knowles wrote:

I think combining this work in a more generic way to enable it to be used by other packages would be more suitable As phpdocumenter starts considering the next version it's probably a good time to think about breaking it into smaller more manageble modules (especially so greg doesnt have to do all the work)... As far as I can see this code would fit into PHP_Render_HTML - a class that enables you to render PHP code in an 'XHTML/... etc. friendly manner.' -SourceLine(line number, formatted source line, path to file) ah - prepends the line number -PreserveWhiteSpace(text) ??? is this really needed -getLink(string) [should take the text in phpDocumentor @see format and parse it to determine if linking is possible] a more generic way of dealing with this: $render->connect('getLink', array($myobject,'getLink')); -returnSee(abstractLink, string) [should take a link class, and the text to display and return an HTML link] again probably a callback $render->connect('getSeeLink', array($myobject,'getLink')); -highlightSource(tokenizer integer/false, token string, bool true if pre-formatted) [enclose the constant in highlighting] I would have though : toHTML($file,$lineStart,$lineEnd); // probably inline cache the file contents array (eg. only store one file at a time so you dont kill memory on large generation) // which loads the file, gets the correct line range (array_split..) // prepends/appends <? ?> // tokenizes it. // renders it and adds line numbers.. // if it contains a docbook tag prior to func/var whatever, then render that as well... -highlightDocBlockSource(phpDocumentor DocBlock token name, token string, bool true if pre-formatted) [enclose docblock tokens in highlighting] // should be covered and picked up by toHTML?? Ontop of this you can do structure parsing using PHP_Parser - all that PHPDocumentor has to concern it'self with is = process control.. -= deciding what data to parse. = build structure of information to output.. (eg. lists of classes, package=>classes, files etc.) = loop through and output stuff. It would be very nice to break phpdocu up into managable small pieces This would enable stuff like this to be done with a few lines of code calling generic renders.. You also should have a look at php's highlight source code, it specifically does code reduction to prevent stuff like this. <span class="p">(</span><span class="p">(</

I do check for this, or at least, I check to make sure its not the same token. I should really check its not the same class, thus reducing the repetition of a span for the tokens which are styled using the same class (like all the structures and such are all styled by the same class)

Regards Alan BTW. Davey should should be tarred and feathered for using auto_prepend_file, heaven for making a project incomprehensible.. :)

This is the *only* way to make this automatically work for *.pds files without needing mod_rewrite or some such. the functionality is there, we we should use it. Although, it should just as easily work with: require_once 'path/to/PDS.php'; will need to test that though. - Davey

Davey wrote:

I've flagged this as a package proposal, but I'm not sure this is right for PEAR, theres probably a lot controversy to be raised over this, and theres lots of work to be done before I'm happy with it... but I will need some help from certain people... I have for example written some parts in this myself to show what I want it to do, but I hope to replace it with code from existing PEAR packges. About: PDS stands for PHP Documented Source, its really where I hoped the .phps stuff to have gone already, however the PHP team seems to have little interest in this part of PHP. PDS does two things: a) Shows Source i) Creates XHTML 1.0 Strict Compliant source view using the default .phps colours ii) This source is (so far in my experience) SMALLER to output than the normal .phps due to the use of <pre> and therefore not relying on a million and one &nbsp; entitities. b) Generates nice basic docs and displays them above the source. i) Will be linked in with the code using anchors to functions and classes ii) needs major work, I wrote this part myself but its a bit scrappy and would benefit from phpDocumentor code I'm sure... problem is extracting the needed code, is it possible to use what I need as it lies within the phpDocumentor code, or will I need to remove it and place it within PDS? iii) output has been smaller than normal .phps even WITH the docs :) PDS works by using the php.ini directives auto_*pend_file, which is one reason I see it not fitting in with PEAR... it does it all itself... theres no user interaction needed... indeed very little can be done beyond specifying a single configuration directive (in a set file) which can specify an alternate CSS file to overwrite the default styles. Unfortunately, the CSS is a bit cryptic, I had a verbose set of CSS classes but in the name of smaller output (one of my goals) I had to shorten them to single letters (or in some cases 2 letters). PDS will work even when there is an error in the file being parsed and indeed the only reason for the auto_append_file is an ob_end_clean() to make sure any are not seen. That is why the source for this is not public (there is literally, nothing else in the file.) You can view PDS in action and its code by visiting http://pixelated-dreams.com/~davey/pds.pre.pds (symlinked to the real code so any changes made will be shown immediately) One of the things I wish to do, but requires parsing beyond my skills is to allow each line to be a <li> (within an <ol>) which can be highlighted onclick so you can see which line are you looking at, and the numbers on the left will be automatically done on the client-side meaning less work for PHP... and when you select the code the numbers will not be selected. The problem with this is my highlighting 'stack' is a simple one, which simply doesn't output an new <span> if it would be the same as the previous one, which means a <span> can cover multiple lines. This is in the interest of small output. I originally was highlighting every token which would alleviate this problem but mean larger output. I need to find some way to detect line ends and put in a </span> and then it needs to use the old <span> to start the new line... whilst writing I have just thought that it can just make a new one based on whatever the token is... still kinda tricky though... will work on this later tonight after I'm done with other stuff. Anyways, huge long e-mail, so I'll let you digest what I've said and any offers of help/flames/comments/whatever are welcome (though flames less so!) - Davey