Distinguish between core and PECL extensions in the Manual

[Sobak]

Hi,

that's @nikic's idea but I think it's good and deserves to be discussed here:

A somewhat related point: The manual currently does not really distinguish
between core extensions and PECL extensions. The only real indication you
get is a small (PECL xxx >= yyy) in the version line, otherwise it might as
well be a core function. This is suboptimal, because a very large fraction
of PHP developers is limited to the use of core extensions, and it's not
possible to see at a glance which is which. I'd like to see a much larger
distinction here. "Large" on the order of switching the header from green
to blue and replacing the "php" logo with "pecl".

http://news.php.net/php.doc/969386436

For now, let's assume it's possible on the side of docs rendering (I think it actually is). What do you think? If you think a general idea is good, how should it be implemented?

[morrisonlevi]

Assuming we can parse that it is a PECL section on the website we could add colors. If not then the markup needs to be altered (which is generated by PhD). The logo would need to be done via PhD as well.

[Sobak]

On the side of PhD we could inject variable like $DOCS_MEMBERSHIP and set it to pecl or core in any other case. Again, these are all optimistic assumptions, but I will look into PhD resources.

Related point: can all these efforts be somehow synchornized with the new release of PhD? I'm in the progress of migrating it to Composer (@morrisonlevi knows that, but others might not) and I think it's a great oportunity to include some changes in this upcoming release.

For the details see http://markmail.org/thread/tpbsky3llwpgfp7o

Also, feel free to suggest your ideas which would require improvements/changes on the side of PhD.

[Sobak]

Work in progress, looks promising

[Sobak]

Here is working proof of concept: Sobak/phd@composer...book-membership

$DOC_MEMBERSHIP can be then used by $setup and thus manual_setup() so it is flexible, I think.

It is based off the composer branch, because it doesn't make sense to implement it earlier. If composer changes won't get merged, for whatever reason, I will rebase it on top of master branch.

Code works but I'm not really sure if it's good. I think @bjori is the most competent person to judge implementation details.

Then, we need agreement upon what we consider PECL and core. I think it would be enough if we mark any extension that was in core in any of PHP version the manual describes. Alternatively we can determine that based on oldest supported version. @salathe?

PS: Membership status come from <?phpdoc extension-membership="{x}" ?>. AFAIK it is not used now, but let me know if I'm wrong. I am - it's used for global changelog generation

[philip]

I'm not sure where else <?phpdoc extension-membership="{x}" ?> is used, but it's used here now:

http://php.net/manual/en/extensions.membership.php

Looks like the options are 'core', 'bundled', 'external', and 'pecl'.

But, the distinction is confusing. What is core? Something that cannot be disabled? Something enabled by default? How is it different than bundled? For example, Calendar and Semaphore are "bundled" as are JSON and SQLITE3, and the latter two are far more common. Well, perhaps JSON (and others) should be listed as core now so maybe this list is simply outdated.

As for a PECL distinction, I suspect a lot more people have PECL extensions like Zip, Mongo, and YAML, then have bundled extensions like Semaphore or COM. Just a guess.

Point is, while I think there should be differentiation somehow, I'm not sure how important the PECL distinction is. I'm not sure how many Linux distributions require the string "pecl" when installing extensions with the likes of apt-get or yum, but I don't think most do. I bet others here know this topic much better than I, though.

[Sobak]

Looks like it's a static file - appendices/extensions.xml to be more precise. Looking at the sources of PhD, this directive is now only used to generate changelog for extensions of given membership status.

It's used like this

<?phpdoc generate-changelog-for-membership="core bundled bundledexternal" ?>

So it de faco generates changelog for everyting, regardless of its membership. Then we could just have pecl and core, I think. But, anyway, it needs a discussion, as you stated many valid points. I'll bring it to the list soon.

[philip]

Interesting, you're (essentially) right. It's fun digging into such things which today reveals scripts/extensions.xml.php that generates extensions.xml by scanning the some source files for extension-membership entries.

I executed it now and there are many updates so I suspect this script was forgotten about by the sands of time. I guess phd could replace it and maybe update it in a more automated fashion. Or, eliminate extensions.xml altogether and simply generate the web page. Looks like the script only adds entries (and not delete them), not sure if that's intentional.

Interesting about generate-changelog-for-membership, nice find.

[Sobak]

I like the idea of autogenerating this file with PhD. It would definitely cause extension-membership to be more up to date. It's tempting but, on the other hand, I'm worried about introducing too many statuses.

Anyway, seems it really should be discussed on the list, with more people participating. Seems we could really get even more from PhD and I really like this beast! Even if I don't completely understand how it works...

Kudos to Hannes, if he will read it, by any chance. I'm truly impressed.