Status of PHP-GTK

[Jace Ferguson]

First of all, I'm excited to see all the recent activity these past few
days.

 

My opinion on the docs is to stick with the php.net standard. I think
migrating the current system to docbook v5 should be a priority. Elizabeth
mentioned in an earlier email that someone had already started the
migration. I'd like to find out who because in about two weeks I will have
quite a bit of free time and I'd be willing to help get the docs migrated
and available for updates.

 

Those are just my thoughts. I'll have the time regardless so I will
definitely find something to do.

 

Jace

[Steph-8]

Hi Jace,

Jace Ferguson wrote:
> First of all, I'm excited to see all the recent activity these past few
> days.
 
Good, ennit? :)
 
> My opinion on the docs is to stick with the php.net standard.

Mine too, because we get concrete assistance from the rest of php.net if we take this approach.

 I think
> migrating the current system to docbook v5 should be a priority.

It should. The work should be stored in CVS HEAD, which means the current docs should be branched and the scripts updated on the server to reflect the new branch name as part of the fixes needed there. (I'm assuming there have actually been updates that weren't followed by a new build..)

Elizabeth
> mentioned in an earlier email that someone had already started the
> migration. I'd like to find out who

So would I...

because in about two weeks I will have
> quite a bit of free time and I'd be willing to help get the docs migrated
> and available for updates.

Woo hoo!

- Steph

> Those are just my thoughts. I'll have the time regardless so I will
> definitely find something to do.
>
>  
>
> Jace
>
>

--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Steph-8]

Andrei Zmievski wrote:
> Elizabeth M Smith wrote:
>>> I'd be inclined to branch php-gtk-doc now and adapt the current
>>> serverside scripts to use that branch while work's in progress on
>>> upgrading to v5 in HEAD. In that case, it'd be best to get the sysadmin
>>> to hit on everything at the same time rather than pester him twice over.
>> Sounds good.
>
> It sounds to me like the current doc system is a big barrier to entry
> for those who want to contribute to the documentation.

It sounds to me like those who want to contribute to the documentation would rather do it in a user-notes kinda way than actually contribute to the documentation. I.e. not need to do the background work like checking the GTK manual or source, kind of thing. That's totally understandable, but I think blaming the use of XML is a bit mean when really it's the lack of user notes that's the issue.

To summarize my
> feelings on this subject: I'd rather have a non-php.net-standard doc
> system that works and allows easy contributions that be stuck in the
> current rut.

Keeping a php.net-standard system means there are always people capable of fixing it when it breaks. Right now, keeping a php.net-standard system also means we should get access to phd, which is a fast-rendering PHP based manual build system (no extra tools required, no not even xsltproc). That factor alone makes it a good investment; the current work on live editing, I'm less convinced about, unless I've misunderstood something major. (Mirrors????)

- Steph

>
> -Andrei
>

--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Justin Martin-4]

Right now, I (FrozenFire), mgdm, and leon are working on generating the
documentation. I have patched the phpdoc docgen.php script to generate
docs for PHP-GTK, except for non-standard stuff like signals.

What we _really_ need is for someone who is quite fluent in the main
documentation system to lend a hand. I am quite well versed in PHP-GTK,
but I know next to nothing about the documentation system. If someone
can pop onto #php-gtk on Freenode, we can get the documentation updated
in a matter of days.

Thanks,
Justin Martin

Steph wrote:

> Andrei Zmievski wrote:
>> Elizabeth M Smith wrote:
>>>> I'd be inclined to branch php-gtk-doc now and adapt the current
>>>> serverside scripts to use that branch while work's in progress on
>>>> upgrading to v5 in HEAD. In that case, it'd be best to get the sysadmin
>>>> to hit on everything at the same time rather than pester him twice
>>>> over.
>>> Sounds good.
>>
>> It sounds to me like the current doc system is a big barrier to entry
>> for those who want to contribute to the documentation.
>
> It sounds to me like those who want to contribute to the documentation
> would rather do it in a user-notes kinda way than actually contribute to
> the documentation. I.e. not need to do the background work like checking
> the GTK manual or source, kind of thing. That's totally understandable,
> but I think blaming the use of XML is a bit mean when really it's the
> lack of user notes that's the issue.
>
> To summarize my
>> feelings on this subject: I'd rather have a non-php.net-standard doc
>> system that works and allows easy contributions that be stuck in the
>> current rut.
>
> Keeping a php.net-standard system means there are always people capable
> of fixing it when it breaks. Right now, keeping a php.net-standard
> system also means we should get access to phd, which is a fast-rendering
> PHP based manual build system (no extra tools required, no not even
> xsltproc). That factor alone makes it a good investment; the current
> work on live editing, I'm less convinced about, unless I've
> misunderstood something major. (Mirrors????)
>
> - Steph
>
>>
>> -Andrei
>>

--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Benjamin Smith-6]

On Friday 17 April 2009 08:28:09 Justin Martin wrote:
> I am quite well versed in PHP-GTK,
> but I know next to nothing about the documentation system.

This scenario is exactly what's got this list so active over the past few
days. You're not the only one in this exact boat. Picking up YADL (Yet Another
Documentation Language) is something that raises the bar to contribution
considerably.

It's a horrible choice: Red Pill or Blue Pill?

Due to the PHP.net frameworks and tools that already exist, there is good
reason to stick with their documentation format at the cost of making it
considerably more difficult (less likely) for developers (such as Madeleine and
myself) who write lots of PHP-GTK code but don't actually develop the code
base itself to contribute documentation. I can't comment on the quality of
these PHP tools, but I'm sure they are quite useful for administrators.

But I am not likely to dive into source code and learn a new documentation
markup language so that I can authoritatively document that you have to
reference a child widget in a particular, non-standard way with widget XYZ.  

But that information is still very useful information to somebody using PHP-
GTK!

Would it be possible to embed an wiki into the documentation so that  
inaccurate or weak information can be simply deleted? (rather than just
commented on, as in comments)

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.
2) The "wiki" documentation, edited only by proven PHP-GTK developers who
aren't necessarily up to #1 above, but have been given access to update the
wiki-appended documentation,
3) Comments, contributed by end users.

This isn't hard to set up since string manipulation is PHP's home turf, and I
*am* volunteering to help set this up.

I've done something similar in commercial web-based products I've worked on in
the past, so that "administrators" (non-programming staff) can update
documentation easily for a given page of our product without making them be
programmers. It works rather well. Typically, I fashion a wiki-url with a bit
of string manipulation from the URL of the page, and make an RPC call to the
wiki to get the document(s) in question.

The wiki itself (EG: phpwiki) can be hosted at an unpublished url, and can be
password protected.

-Ben

--
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.


--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Andrei Zmievski]

Steph wrote:
> It sounds to me like those who want to contribute to the documentation
> would rather do it in a user-notes kinda way than actually contribute to
> the documentation. I.e. not need to do the background work like checking
> the GTK manual or source, kind of thing. That's totally understandable,
> but I think blaming the use of XML is a bit mean when really it's the
> lack of user notes that's the issue.

So, when can we have user notes back?

-Andrei

--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Steph-8]

Hi Benjamin,

> This scenario is exactly what's got this list so active over the past few
> days. You're not the only one in this exact boat. Picking up YADL (Yet Another
> Documentation Language) is something that raises the bar to contribution
> considerably.

XML is Yet Another Documentation Language?

> Due to the PHP.net frameworks and tools that already exist, there is good
> reason to stick with their documentation format at the cost of making it
> considerably more difficult (less likely) for developers (such as Madeleine and
> myself) who write lots of PHP-GTK code but don't actually develop the code
> base itself to contribute documentation. I can't comment on the quality of
> these PHP tools, but I'm sure they are quite useful for administrators.

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'.

> But I am not likely to dive into source code and learn a new documentation
> markup language so that I can authoritatively document that you have to
> reference a child widget in a particular, non-standard way with widget XYZ.
>
> But that information is still very useful information to somebody using PHP-
> GTK!

So we fix user notes et voila, the info is available.

> Would it be possible to embed an wiki into the documentation so that  
> inaccurate or weak information can be simply deleted? (rather than just
> commented on, as in comments)

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.)

> 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.

> 2) The "wiki" documentation, edited only by proven PHP-GTK developers who
> aren't necessarily up to #1 above, but have been given access to update the
> wiki-appended documentation,

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.

> 3) Comments, contributed by end users.
>
> This isn't hard to set up since string manipulation is PHP's home turf, and I
> *am* volunteering to help set this up.

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.

Anyone with a php.net address can log into the admin page, but auth is further restricted via whitelisting for some activities. Restricted access does not currently include the ability to edit the existing notes (from the former manual), but does include core items like the ability to turn notes or email notifications on or off.

> I've done something similar in commercial web-based products I've worked on in
> the past, so that "administrators" (non-programming staff) can update
> documentation easily for a given page of our product without making them be
> programmers. It works rather well. Typically, I fashion a wiki-url with a bit
> of string manipulation from the URL of the page, and make an RPC call to the
> wiki to get the document(s) in question.
>
> 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'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?

- Steph

>
> -Ben
>


--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Steph-8]

Andrei Zmievski wrote:
> Steph wrote:
>> It sounds to me like those who want to contribute to the documentation
>> would rather do it in a user-notes kinda way than actually contribute
>> to the documentation. I.e. not need to do the background work like
>> checking the GTK manual or source, kind of thing. That's totally
>> understandable, but I think blaming the use of XML is a bit mean when
>> really it's the lack of user notes that's the issue.
>
> So, when can we have user notes back?

I'm on it. It wasn't actually as bad as I remembered - just the NNTP-checking stuff was a seriously bad idea.

- Steph
>
> -Andrei
>

--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Benjamin Smith-6]

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@...?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.


--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Elizabeth M Smith]

Yikes - I was gone for the weekend and ...

For those asking for a wiki - php.net currently has a wiki up
(wiki.php.net) and it's so far been a very good experience.  However
access is controlled pretty well (cvs access credentials and cvs karma
are used, in additional other users can register and are given access to
certain areas after mailing the php.webmaster list)

As a compromise could we maybe have a php-gtk section on the wiki for
those that want to put up tips, keep track of the doc migration status
(maybe I'd stop being lazy and put up a page with what I'm currently
playing with)

Just an idea.

and Steph, if you'd have some time to talk to leon, mgdm and frozenfire
they'd love some help.  I have a cursory understanding of the system but
they need someone who knows the phpgtkdoc.dtd and can "merge in" the
parts that will be needed above and beyond the php.net's .dtd ;)

Thanks,
Elizabeth

--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[Steph-8]

Elizabeth M Smith wrote:
> Yikes - I was gone for the weekend and ...

Tell me about it :)

> For those asking for a wiki - php.net currently has a wiki up
> (wiki.php.net) and it's so far been a very good experience.  However
> access is controlled pretty well (cvs access credentials and cvs karma
> are used, in additional other users can register and are given access to
> certain areas after mailing the php.webmaster list)

That's on Pierre's box, no?
The main problem with making the wiki part of the gtk.php.net site was that we don't know whose server we're going to be on next week, if you follow.

> As a compromise could we maybe have a php-gtk section on the wiki for
> those that want to put up tips, keep track of the doc migration status
> (maybe I'd stop being lazy and put up a page with what I'm currently
> playing with)
>
> Just an idea.

Not a bad idea either.

> and Steph, if you'd have some time to talk to leon, mgdm and frozenfire
> they'd love some help.  I have a cursory understanding of the system but
> they need someone who knows the phpgtkdoc.dtd and can "merge in" the
> parts that will be needed above and beyond the php.net's .dtd ;)

I went to talk to them but they didn't talk back - I guess we're all in different timezones. (Actually frozenfire did eventually speak - he was on his way out to work, and it was 9pm here.) If they'd contact me via email it'd be easier.

Cheers,

- Steph

>
> Thanks,
> Elizabeth
>

--
PHP-GTK General Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php