Re: Package Proposal: Tools and Utilities: PDS

Hi Davey, This is a great idea, and is in fact exactly what phpDocumentor does. The only difference is that the colors are more flexible and are based upon CSS, so it is possible to make the source highlighting match what you're used to seeing in your favorite IDE. If you're not satisfied with phpDocumentor's implementation, what you can do is create an object that defines a few methods: -SourceLine(line number, formatted source line, path to file) -PreserveWhiteSpace(text) -getLink(string) [should take the text in phpDocumentor @see format and parse it to determine if linking is possible] -returnSee(abstractLink, string) [should take a link class, and the text to display and return an HTML link] -highlightSource(tokenizer integer/false, token string, bool true if pre-formatted) [enclose the constant in highlighting] -highlightDocBlockSource(phpDocumentor DocBlock token name, token string, bool true if pre-formatted) [enclose docblock tokens in highlighting] You would also have to disable class member linking, as that requires access to the complete phpDocumentor hierarchy. This can be done by removing the references to event PARSER_EVENT_CLASS_MEMBER and to class/variable/method parsing. However, this is tricky, so best would be to subclass HighlightParser and modify handleClass, handleVar, handleMethod, handleClassMember methods to do what you need with your special class. As you can see, this would involve a little bit of work. However, I understand your desire for a small solution to better highlighted source, and this is a great idea. Since the overlap with what phpDocumentor does is 100% in terms of highlighting, perhaps we could combine our efforts? phpDocumentor is modularized enough that it would be simple to write a converter extension that combined the source with docs for a page and spits them all out in one page for viewing, and there would be no need for all the configuration stuff that is used prior to parsing a normal offline project. Greg 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