Re: Status of PHP-GTK

On Saturday 18 April 2009 11:32:01 you wrote: > XML is Yet Another Documentation Language? The specific schema used is what I refer to as "yet another documentation language". It's not that knowing XML is an issue, it's that knowing all the rules, ramifications and permutations of this schema that's the issue. > These PHP tools (AKA phd) simply build the docs. You can try it out with > phpdoc, where it's already used, if you're interested. It renders a whole > lot faster than xsltproc, and it also means you don't need any further > tools beyond PHP itself to build the manual. I'm not 100% sure what the > benefit of live updates is - possibly the idea is that you can build the > docs locally then make alterations via the browser, rebuild to test, > commit. That would make sense because it removes the XML 'barrier to > entry'. Tell me more about this "live updates"... ? > > But that information is still very useful information to somebody using > > PHP- GTK! > > So we fix user notes et voila, the info is available. Forward progress is forward progress - I strongly agree with this next step! > What's the difference, really? Inaccurate or weak info can be deleted > anyway, or moved into the manual and given 'official' status. There are a > _lot_ of people with php-gtk-doc access, and over 2,000 people with access > to notes admin (both for the PHP manual and for the PHP-GTK manual, anyone > with a php.net account of any kind can edit user notes.) I did not know this. > > This would provide basically three tiers of documentation on the same > > page: > > > > 1) The "root" documentation, in the tagged documentation format, edited > > only by language developers. > > Why so? I wrote half the first manual without being a language developer. I > also wrote a previous unofficial manual from a user perspective, back in > the day; the biggest problem with that was that I didn't know why things > were as they were, so I couldn't explain behaviours. I applaud your efforts, sir! Thank you thank you thank you! There was another comment recently about doing "proper research" of which I was thinking. PS: Thank you! > We could (once notes are rolling) open up access to notes. There is a > precedent for this: there are people with editing rights for the PHP manual > notes who do not have a CVS account. Great! > I had it to trial status before now; still in CVS; nobody's touched it in > the last 3 years but it doesn't mean the code isn't there. In fact I've > been looking at it today... the problems with it were 1) I hadn't made it > easy to set up a local version (have done so locally now), and 2) I'd some > clever idea about using the php.net NNTP server rather than actual people > to control the notes queue. That part really didn't pan out and I'll > happily spend the next hour or so killing it. The rest of the system > appears to work fine, just we'd need willing moderators to join the ML > where notifications are sent. According to the config file, that would be > the php-gtk-webmaster list. // SNIP // > > The wiki itself (EG: phpwiki) can be hosted at an unpublished url, and > > can be password protected. > > What's the difference between a password-protected wiki and > password-protected notes admin? I was picturing something that visually would look as if the wiki section was more part of the documentation at the top, rather than a "note" which 27 followups improving on a bad code sample. (as has already been complained about) Myself, I've LOVED the notes in the PHP-GTK website - just do a search for my email address as a contributor in the phpgtk1 docs. I make it a point to leave a note anytime I had to do further searching to get a job I'm trying to do, done. BTW: I have a fairly large, stable code base written in PHP-GTK1 and the cost of jumping to php-gtk2 is pretty high, so I haven't made the switch, yet. I've contemplated building a set of wrappers so that there are widgets in PHP5-GTK2 that have a similar API to comparable widgets PHP4-GTK1, and I've even started a few times, but that's another story. > I'd be bothered about hosting a wiki on a php.net server again, following > the experience we had last time around. So the part about the 'unpublished > url' sounds good, but then - Frederic has a rather good community site that > already offers this kind of approach. Why not just make more of the > community sites from the project homepage, thereby allowing php.net to do > what it does best and the community sites to do what they do best? Wikis have their problems. Did you read about the P2P network set up at a college on the US East Coast using wikis as the distribution medium? But they are very useful! Here's what I do in order to tie documentation in a Wiki to a section of a complex website. I haven't checked this for bugs, but it should give the idea. And if this is already patently obvious, please be gentle. Let's say you have a page, and you want to embed content from a wiki elsewhere in there. http://www.mydomain.com/path/to/index.php 0) Edit the wiki's templates so that the below comment tags appear just before/after the changeable content on each wiki page. 1) within the file index.php, In PHP, turn that into a wiki word. EG: $tmp = preg_replace("/[^a-zA-Z]/", ' ', $_SERVER['SCRIPT_NAME']); $wikiword = str_replace(' ', '', ucfirst(strtolower($tmp)); Now $wikiword should have something like 'PathToIndexPhp'; 2) Now, get the wiki content, stick it into the page. $url="http://$htuser:$htpass@wiki.mydomain.com?page=$wikiword"; // YOU SHOULD HAVE EMBEDDED THESE TAGS INTO THE WIKI // TEMPLATE SO WE CAN EXTRACT THE CONTENT HERE $contentBegins = '<!-- BEGIN Content -->'; $contentEnds='<!-- END Content -->'; $content=file_get_contents($url) echo substsr($content, strpos($content, $contentBegins)+strlen($contentBegins), strpos($content, $contentEnds)); I usually leave a link to the wiki in the output so that those with appropriate passwords can "jump right in" if they notice a documentation bug. Of course, they'll need to enter the password: echo "<A HREF='http://wiki.mydomain.com?page=$wikiword'>edit</a>"; This is obviously a very simple form - I usually have to re-map links within the content from the wiki to maintain cohesion, and a few other details. But it's not hard, and it works very, very well for me, in that I can effectively let the support staff at my company (who aren't programmers but who answer the phones) update the documentation in a way that looks "official" in real-time. I use Apache .htaccess passwords to protect the wiki from abuse. -Ben PS: If you are still reading, thank you again! -- This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean.