Re: [PHP-DOC] How to document 'not implemented, sorta' stuff?
On Jun 7, 2010, at 3:47 PM, Philip Olson wrote: There are several features in PHP that are not implemented [yet], including roughly 13 DOM classes. Well, they are sorta (but not really) implemented. How should we deal with this? Just my 2¢ but if something is not (yet) implemented, it doesn't exist and thus shouldn't be referenced in any end-user documentation. I could never tell my clients about x functionality unless it is, well, functional! Doing otherwise could be interpreted as being less than honest. HTH Ted Stresen-Reuter http://chicagoitsystems.com
Re: [PHP-DOC] oop5 basic rewrite informal RFC
On Sep 9, 2009, at 2:02 PM, Hannes Magnusson wrote: On Wed, Sep 9, 2009 at 13:20, Brandon Savagebran...@brandonsavage.net wrote: This documentation already exists in that section. I'll amend my diff to reference this section. Something along the lines of PHP 5's object model also significantly changes the way objects are handled, and each variable representation contains an object identifier instead of the object itself. Passing objects by reference is no longer necessary. See Objects and References. Sounds good (but please stop top-posting). Since this chapter is being heavily worked on now, I'd like to see the PHP5 object model to be talked about as nothing is more normal. As in, don't compare it to php4 or say stuff like no longer have to.. That should be in the upgrade guides, or in a special appendix called differences compared to php5 in the php4-oo docs. -Hannes From a (natural) language learning perspective, this is by far the preferred method. Good call! Ted Stresen-Reuter http://tedmasterweb.com
Re: [PHP-DOC] Patches
On Jul 16, 2009, at 2:04 PM, Moacir de Oliveira moacirdeoliveira@gmail.com wrote: Patch Explanation Outstanding explanation. Gave me some ideas for how to improve my own code. Ted Stresen-Reuter
Re: [PHP-DOC] docs to svn business
On Jul 9, 2009, at 1:24 AM, Philip Olson wrote: How are CVS Revision numbers used today? The best feature of po is that translation text is marked as 'fuzzy' when the main text is changed. If we could do the same with our docbook translation files whenever the en file is committed then we have the same benefits imo. I'm wondering if CVS Revision numbers could be replaced by a 'fuzzy' markup tag...? When a translator updates a translation (a file), they write which CVS Revision in EN it's synced to. So, later when the EN version is updated we then know that the translated is outdated. And all of our translation tools rely on the incremental nature of CVS revision numbers. A couple of options Create an md5 hash on the version you are translating and use that to uniquely identify it. If the EN version is modified by even a single space, the hash will change and you'll know the files are out of sync. What you won't know is just how far out of sync (but does that really matter?) If using XSLT at some point, use generate-id() function to generate a unique id of EN and use that to uniquely identify the version. As with md5, any minor changes will cause a different id to be generated. Neither of these is quite as elegant as progressive version numbers. I suspect md5 would be the best option. Ted Stresen-Reuter http://tedmasterweb.com (I'm on vacation, but this thread is quite fascinating)
Re: [PHP-DOC] docs to svn business
On Jul 9, 2009, at 6:31 PM, Hannes Magnusson wrote: Create an md5 hash on the version you are translating and use that to uniquely identify it. If the EN version is modified by even a single space, the hash will change and you'll know the files are out of sync. What you won't know is just how far out of sync (but does that really matter?) That will be the same as using the SVN revision numbers. Also, and I only realized this after researching a little more, if you create an md5 hash on a single file, and then paste it into that file where the current rev # is, the hash itself will change and you're back to square one! Ted
Re: [PHP-DOC] docs to svn business
On Jul 9, 2009, at 7:18 PM, Niel Archer wrote: Why is this a problem? SVN revision numbers are incremental as well. I don't see the difference between tying a translation to CVS-123456 and SVN-123456? I'm not particularly familiar with CVS (fortunately), so someone please correct me if I'm wrong, but I believe it gives each file a revision number to uniquely identify its version. Where as SVN only has a single revision number for the entire repository. It is true that SVN increments the rev number on each commit. However, if you use the ID keyword (or REV keyword), it will only be updated when the file is changed, not when other files are changed and committed. As Hannes asks in another email in this same thread, is knowing how far out of sync a translation is really a useful feature? Isn't it enough to know that something is no longer in sync? And to which I would add: wouldn't it be great if we could simplify things by dropping existing functionality in exchange for ___ (fill in the blank)? In my own work I am constantly bogged down by clients' needs to maintain existing (10-year old) functionality that almost nobody uses. I wish some of the translators or other doc people would chime in on this. By dropping this functionality we could speed things right along and make everyone's life easier (just a suggestion, please be kind in your replies...) Too bad Subversion doesn't have a $Log$ keyword to help translators see what changes have been made to a source file: http://subversion.tigris.org/faq.html#log-in-source Ted Stresen-Reuter http://tedmasterweb.com
Re: [PHP-DOC] [HEADSUP] Call for help
On Jul 5, 2009, at 10:25 AM, Peter Cowburn wrote: For what it's worth, I'd rather see kick-ass awesome in there than it being left out. :) I agree! Ted S-R http://tedmasterweb.com
Re: [PHP-DOC] Re: [HEADSUP] Call for help
On Jul 5, 2009, at 2:57 PM, Peter Beverloo wrote: With the documentation moving to PO files soon (as well as changes around the PhD editor GSoC project) I follow this list pretty closely but I must have missed this (rather important) news item. When will the documentation move to PO files? How will this change the translation process and source files? Is this move documented somewhere? In short, is there an other list where such decisions are made that I'm unaware of? Thanks in advance. Ted Stresen-Reuter http://tedmasterweb.com
Re: [PHP-DOC] Conforming documentation style - how to document classes
On Jun 15, 2009, at 6:26 PM, Philip Olson wrote: On Jun 15, 2009, at 1:18 AM, G. T. Stresen-Reuter wrote: Hi, I'm not a big contributor (in fact, haven't done much more than test PhD and send some feedback) but I do work with the raw documentation quite a bit. I've found some apparent irregularities in how classes are documented. For example, the tidy.html has both procedural and OO versions of the function. The procedural version follows the convention found in other function definitions but the OO version seems to be missing the CLASSSYNOPSIS, OOCLASS, etc. elements thus there is no way to select just the OO methods. Is there an exemplary class definition in the existing documentation I could use as a foundation for fixing the structure of the Tidy classes (and other classes that I periodically run across with odd structure)? Greetings Ted, Do you feel like determining what might work best? He he he... no! There does seem to be some consensus among class definitions so, keep reading... On Jun 16, 2009, at 9:06 AM, Hannes Magnusson wrote: I really like what Jakup did with the ext/datetime docs. I simply don't know enough about programming and DocBook to be able to opine with any authority. I'll leave the decision on what format to follow to the experts and do my best to implement whatever decision is made. (and FWIW, I recently discovered http://www.php.net/manual/en/extensions.php and have simply stopped using the other categorizations as I find it hard to determine what category the function I'm looking for will be in) This could begin the process of knowing. Let's list all OOP +Procedural API extensions then determine the differences, and use one syntax. This may or may not be a complete list (likely not, but close): - Date/datetime (toc has both) - Dir (toc has both (sort of)) - DOM (not really, but domxml is procedural) - Fileinfo (toc is procedural) - Intl (toc is oop) - MaxDB (toc is procedural) - MySQLi (toc is oop) - SQLite (toc is procedural) - Tidy (???) - XMLWriter (toc is oop) While some were Procedural but are now OOP (so they differ): - Imagick (procedural api not listed (which seems fine, as it's dead/ old)) - Tidy? (???) - Zip (partial procedural exists for BC, needs clearer definition of difference) Unsure how to classify some: - Rar (appears to use both together (weird)) - SimpleXML (not sure why the procedural exists...) This list is more than big enough to start. It can always be added to! Summary: - We do it differently per extension, so are inconsistent - The TOC for these also differ (lists OOP and/or Procedural) - This is a problem Notes: - Eludes to it: http://cvs.php.net/viewvc.cgi/phpdoc/RFC/skeletons/method.xml - Docgen commit to handle it: http://news.php.net/php.doc.cvs/3884 So, if I understand the purpose of docgen, maybe we could start with skeleton functions and classes in PHP and use them to create the skeletons for the documentation? Ted PS: Should I be cc'ing people in addition to replying to the list? Personally I prefer to receive only one email per thread.
[PHP-DOC] Conforming documentation style - how to document classes
Hi, I'm not a big contributor (in fact, haven't done much more than test PhD and send some feedback) but I do work with the raw documentation quite a bit. I've found some apparent irregularities in how classes are documented. For example, the tidy.html has both procedural and OO versions of the function. The procedural version follows the convention found in other function definitions but the OO version seems to be missing the CLASSSYNOPSIS, OOCLASS, etc. elements thus there is no way to select just the OO methods. Is there an exemplary class definition in the existing documentation I could use as a foundation for fixing the structure of the Tidy classes (and other classes that I periodically run across with odd structure)? Thanks in advance. Ted Stresen-Reuter http://tedmasterweb.com
Re: [PHP-DOC] PhD Plugin System
Hi, On May 1, 2009, at 7:28 PM, Moacir de Oliveira wrote: Another example of theme would render the funcindex.xml file from the PHP documentation source.[4] [4] - http://bugs.php.net/bug.php?id=47651 I have one or two XSL stylesheets that were able to produce a complete list of keywords on previous versions of .manual.xml, but the format has changed and the stylesheets need to be updated (which I'm working on). You can see a sample of the stylesheet here: http://tinyurl.com/phpfuncstylesheets I hope you find that useful. Ted Stresen-Reuter http://tedmasterweb.com
Re: [PHP-DOC] user comments of the future
I too feel compelled to participate in this thread... On Apr 1, 2009, at 9:06 AM, Richard Quadling wrote: 2009/3/31 Philip Olson phi...@roshambo.org: As far as using a fancy looking comment system, I would vote for it. Everything is going web 2.0 with the ooohhh and ahhhs (gmail is a prime example, there are tons of libraries and sample code for Javascript effects). Almost every site I visit uses some sort of Javascript or AJAX in background (even vBulletin has gone AJAX to some extent). Yeah, people almost expect such features these days. Personally I think there is a usability case to be made for some Ajax- style features as well. My clients find edit in place to be a very easy feature to understand. So, for me, it's not just about being fancy or following the latest trend. After all, if it *were* about that, we'd all be using RoR by now... ;-) [snip snip] You don't need 2 versions. Even with the most complex of sites, it should be developed without JS initially. You then use unobtrusive JavaScript inclusion to modify the page as appropriate. This technique allows the widest range of clients with the least amount of effort. It is pretty much a given that the user-agent string is useless for anything other than truly rudimentary browser analysis. The browscap.ini file from Gary Keith (http://browsers.garykeith.com/stream.asp?PHP_BrowsCapINI) is fine and dandy but is updated pretty much every week. New user-agent strings are constantly being created. And, having said that, the agent string doesn't actually tell you if JS is supported or enabled. That can only be done on the client. So, they say don't bother. Assume it isn't. That way you site works with no special effects, AJAX, etc. Add JS to the mix and its a few form actions overridden, some observers and voila, Web 2.0 in all its glory. [snip snip] I use Prototype/Scriptaculous (both served by Google API, so the more sites that use the Google API cache the better for all). When using AJAX I supply a JS callback (using the JSONP concept) to let server side know the style of call being made. Essentially this means 1 set of HTML/CSS (with or without JS) and 1 set of server side scripts which are told to generate HTML or JSONP output. All the server side logic should be identical and it is just the output that is tuned. This is totally the way to do it and there are a few frameworks out there that lend themselves to just such an approach. If you think of it as an MVC approach, in the View stage you analyze the format of output requested and respond accordingly. Richard really does understand how it should be done. Also, it should be noted that for people who aren't able to render the JS (such as screen readers), accessibility is maintained. 1+ for using this approach... G. T. Stresen-Reuter Web: http://tedmasterweb.com Blog: http://tecnotertulia.com Twitter: http://twitter.com/tedmasterweb
Re: [PHP-DOC] Re: Function Index
On Mar 31, 2009, at 11:04 AM, Richard Quadling wrote: So is there anything I can do? -- - Richard Quadling My question is, were those statistics about undocumented functions etc. a result of problems with PhD or a genuine reflection of functions that are missing documentation? My guess is the latter... Thanks in advance. G. T. Stresen-Reuter Web: http://tedmasterweb.com Blog: http://tecnotertulia.com Twitter: http://twitter.com/tedmasterweb
Re: [PHP-DOC] XHTML (was: A blank page shows)
On Dec 24, 2008, at 6:49 AM, Hannes Magnusson wrote: No need for the rendered docs to be XML parsable, if you need to do some magic against the docs then use the DocBook XML. Good point and in fact, I've changed my mind on the need for totally valid XHTML... I'll keep watching the list for an opportunity to help, though. Ted S-R
Re: [PHP-DOC] XHTML (was: A blank page shows)
On Dec 23, 2008, at 4:10 PM, Hannes Magnusson wrote: There are several cases which we simply cannot fix Do you have one documented? I do a lot of XSLT-type stuff and it seems to me that if we're starting with valid XML (.manual.xml) and XHTML is in many respects HTML XMLified that it should be possible... And besides, I like a good challenge... Thanks in advance. Ted Stresen-Reuter http://tedmasterweb.com
Re: [PHP-DOC] PHP doc XML layout conventions - tool available?
On Oct 2, 2008, at 12:10 PM, Hannes Magnusson wrote: On Thu, Oct 2, 2008 at 13:06, Anthony Bedford [EMAIL PROTECTED] wrote: Hi, has anyone out there written a script that will help reformat an XML doc to the PHP doc style? I have a large(ish) table in particular that I don't want to reformat by hand if I can get away with it. Nope :( The closes you can get are the various scripts (CVSROOT/phpdoc/scripts/) that generate phpdoc XML from c sources or reflection. This project has a stylesheet that converts the PHP docs to clippings (used by BBEdit) and _might_ be a foundation upon which you can use to develop a stylesheet that will do what you want: http://tinyurl.com/4bhctg Check out bbedit_php_glossary_v2.xsl Sincerely, Ted Stresen-Reuter http://tedmasterweb.com
[PHP-DOC] Configure failing with EntityRef: expecting ';' and chunk is not well balanced error
I'm trying to build the PHP docs locally but configure.php is failing with the following error: == Loading and parsing manual.xml... failed. ERROR (/Users/tedsr/phpdoc2/phpdoc/en/install/pecl.xml:147:21) url.pecl.submit. -^ EntityRef: expecting ';' ERROR (/Users/tedsr/phpdoc2/phpdoc/en/install/pecl.xml:unknown) chunk is not well balanced Previous errors too severe. Stopping here. Eyh man. No worries. Happ shittens. Try again after fixing the errors above. == I looked (briefly) at the source and found that there are multiple uses of $url throughout the source so fixing that one instance doesn't seem like a solution. Rather, it seems, I'm missing an entity declaration (or something like that). I seem to recall some emails on the list that might have been related, but I don't recall what the solution was (or if they were even related). Sorry This is based on the HEAD of phpdoc checked out a few minutes ago. Any ideas? Thanks in advance. Ted Stresen-Reuter http://tedmasterweb.com
Re: [PHP-DOC] [HEADSUP] New phpweb branch
On Aug 22, 2008, at 1:39 AM, Jean-Sébastien Goupil wrote: That looks like really nice for now. I have just few comments about the new design. Personally, the first thought I had was Mmm, it looks like a little less professional, but looks like the new era of web. And I spent just 10 minutes browsing it, I have no idea how far you are with updating the design but I just want to tell you what I think: - the code examples don't stick out enough - and the user contribution looks like it's part of the actual documentation content (I don't think it's good?) I know my feedback is unsolicited so I'll try to make it as constructive as possible... One principal of design is contrast[1]: make things sufficiently different to communicate their difference in meaning. For example, headers are sufficiently larger, bolder, or different in color so as to not be confused with other text elements that follow. I think there are three facets of the existing design that are good examples of contrast: - the white space used between headings and body text; - the light blue boxes on a white background for each section; - the indenting of the Parameters section. I find that the contrast between elements in the new design is not sufficient enough (for my weary, old eyes) and requires a tad bit more mental focus to read. Also, I bumped up the size of the text in my browser by one notch and found things much easier to read. The text size is _really_ small in Safari. Although personally I like the rounded corners and color scheme, I think accessibility experts may find the lack of contrast between links and background to be less than ideal.[2] I know design by committee is an exercise in frustration so I hope my feedback isn't taken the wrong way and those responsible find *something* valuable in these comments. Respectfully, Ted Stresen-Reuter http://tedmasterweb.com [1] The design principal of CRAP was originally presented in Robin William's The Non-Designer's Design Book and is partially reproduced here http://www.lifehack.org/articles/communication/design-better- with-crap.html [2] http://juicystudio.com/services/csstest.php#contrast
Re: [PHP-DOC] (was: (spam title removed))
On Jul 28, 2008, at 12:59 PM, Hannes Magnusson wrote: On Mon, Jul 28, 2008 at 13:14, Richard Quadling [EMAIL PROTECTED] wrote: How are these appearing on the list? [snip] I thought you had to be a subscriber? Nope. But you do have to respond to the challenge/response mail. I have no idea how the filter works exactly, but I assume since the from address is phpdoc@ it bypasses the filter... -Hannes Might they be using a technique similar to the one described in this video? http://video.google.com/videoplay?docid=-8246463980976635143 Ted S-R
Re: [PHP-DOC] [ANNOUNCE] PhD 0.3.0 Released!
On Jul 24, 2008, at 9:54 PM, Hannes Magnusson wrote: Hi all! Next minor release of PhD, 0.3.0, has been released! For a full release history, see http://doc.php.net/phd/ To upgrade from previous releases: pear upgrade doc.php.net/phd-beta Hi Hannes, I'm looking forward to trying out the new version, however, when I tried: pear upgrade doc.php.net/phd-beta I got the following result: Nothing to upgrade I'm pretty sure I'm running either 0.2.6 or 0.2.7... Any way I can find out for sure? Thanks in advance. Ted Stresen-Reuter
Re: [PHP-DOC] [ANNOUNCE] PhD 0.3.0 Released!
On Jul 24, 2008, at 10:20 PM, Hannes Magnusson wrote: I'm pretty sure I'm running either 0.2.6 or 0.2.7... Any way I can find out for sure? phd -V gives you the installed version. /usr/local/php5/bin/phd -V [23:35:40] PhD version: 0.2.3 [23:35:40] Copyright (c) 2008 The PHP Documentation Group Very weird. Almost certainly an issue with my pear installation. Thanks for confirming that it does work, though. At least I know there's hope! Ted S-R
Re: [PHP-DOC] [ANNOUNCE] PhD 0.3.0 Released!
Getting there... see below... Are you sure you want to go down this path with me? Your help is greatly appreciated, but if I poke around enough I'll eventually get it installed... On Jul 24, 2008, at 10:40 PM, Hannes Magnusson wrote: On Thu, Jul 24, 2008 at 23:37, G. T. Stresen-Reuter [EMAIL PROTECTED] wrote: On Jul 24, 2008, at 10:20 PM, Hannes Magnusson wrote: I'm pretty sure I'm running either 0.2.6 or 0.2.7... Any way I can find out for sure? phd -V gives you the installed version. /usr/local/php5/bin/phd -V [23:35:40] PhD version: 0.2.3 [23:35:40] Copyright (c) 2008 The PHP Documentation Group Try pear uninstall'ing it and then install: [EMAIL PROTECTED]:~$ sudo pear uninstall doc.php.net/phd-beta uninstall ok: channel://doc.php.net/PhD-0.3.0 [EMAIL PROTECTED]:~$ sudo pear install doc.php.net/phd-beta downloading PhD-0.3.0.tgz ... Starting to download PhD-0.3.0.tgz (39,686 bytes) ..done: 39,686 bytes install ok: channel://doc.php.net/PhD-0.3.0 That seemed to work, but... here's the terminal output: tedsr$ sudo /usr/local/php5/bin/pear uninstall doc.php.net/phd-beta Password: uninstall ok: channel://doc.php.net/PhD-0.2.3 tedsr$ sudo /usr/local/php5/bin/pear install doc.php.net/phd-beta downloading PhD-0.3.0.tgz ... Starting to download PhD-0.3.0.tgz (39,686 bytes) ..done: 39,686 bytes ERROR: doc.php.net/PhD: conflicting files found: phd/formats/xhtml.php (__uri/phd) phd/include/PhDFormat.class.php (__uri/phd) phd/include/PhDTheme.class.php (__uri/phd) phd/include/PhDHelper.class.php (__uri/phd) phd/include/PhDReader.class.php (__uri/phd) phd/include/PhDPartialReader.class.php (__uri/phd) phd/include/langs/bg.xml (__uri/phd) phd/include/langs/cs.xml (__uri/phd) phd/include/langs/de.xml (__uri/phd) phd/include/langs/en.xml (__uri/phd) phd/include/langs/it.xml (__uri/phd) phd/include/langs/ja.xml (__uri/phd) phd/include/langs/pl.xml (__uri/phd) phd/include/langs/pt_BR.xml (__uri/phd) phd/include/langs/ro.xml (__uri/phd) phd/themes/php/bightml.php (__uri/phd) phd/themes/php/chunkedhtml.php (__uri/phd) phd/themes/php/phpdotnet.php (__uri/phd) phd/themes/php/phpweb.php (__uri/phd) phd/config.php (__uri/phd) phd/LICENSE (__uri/phd) phd/mktoc.php (__uri/phd) phd/TODO.RENDERER (__uri/phd) I suspect there is a --force option for pear, but not sure how to invoke it (nor if it is appropriate in this context). Ted S-R
Re: [PHP-DOC] [ANNOUNCE] PhD 0.3.0 Released!
On Jul 24, 2008, at 10:53 PM, Brett Bieber wrote: pear uninstall __uri/phd pear install doc.php.net/phd-beta BINGO! Thanks for the lessons (and for PhD)! Ted S-R
Re: [PHP-DOC] Machine-readable PHP documentation?
On Jun 4, 2008, at 12:23 AM, Edward Z. Yang wrote: Ben Dilts wrote: I can't seem to find information on how to make complete XML files of the reference docs. The en/reference/*/functions/*.xml files are not actually valid XML, as they don't have a DOCTYPE and don't define all the custom XML entities they use. How do I transform these sources into complete, valid XML documents? Use configure.php. An outstanding project is to make all of PHP's documentation sources standalone valid XML files, but for now, you'll need to glom them all together. And then look for .manual.xml (not the dot at the start of the name - it is a hidden file) Ted Stresen-Reuter http://tedmasterweb.com/php-bbedit-clipping-set/
