Re: [PHP-GTK] 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:[email protected]?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.