Unix manual pages for PHP functions
Did you know that unix manual pages for PHP functions and methods existed?
For a while I had vim configured to run reflection when I hit "K", but after the PHP documentation team released unix manual pages for PHP I now get the manual page in all its glory; function description, parameter descriptions, return values, examples, notes, see also and everything you are used to see from the online manual.
Its awesome.
As many PHP functions use "standard names" the documentation team decided to not install the manual in the standard man directory.
When you install the unix manual package you get a little shell script (called "pman") which runs the normal "man" command for you, and sets the manual directory to wherever you installed the package.
To install the PHP manual as unix manual pages:
If you are running very old pear version you need to "discover" the doc.php.net channel first:
And then run the command above.
The manual will install into whichever directory you have specified as the "doc_dir" in the pear configuration, and the "pman" script into "bin_dir".
By default I believe pear sets the "bin_dir" to something that is already in your $PATH so you should be able to execute "pman strpos" now.
In VIM you need to update the "keywordprg" config (or add it, if it doesn't exists already) to "pman":
Now open up a .php file, place your cursor over some PHP function and hit "K", you should get the manual page for that function \o/.
Unfortunately Symfony, Zend Framework, Doctrine, and other frameworks/libraries/.. do not distribute unix manual pages yet so I use the Taglist plugin to jump to the code.
Looking forward to when these frameworks start producing unix manual pages, so much easier to read :D
-Hannes
For a while I had vim configured to run reflection when I hit "K", but after the PHP documentation team released unix manual pages for PHP I now get the manual page in all its glory; function description, parameter descriptions, return values, examples, notes, see also and everything you are used to see from the online manual.
Its awesome.
As many PHP functions use "standard names" the documentation team decided to not install the manual in the standard man directory.
When you install the unix manual package you get a little shell script (called "pman") which runs the normal "man" command for you, and sets the manual directory to wherever you installed the package.
To install the PHP manual as unix manual pages:
$ pear install doc.php.net/pman
If you are running very old pear version you need to "discover" the doc.php.net channel first:
$ pear channel-discover doc.php.net
And then run the command above.
The manual will install into whichever directory you have specified as the "doc_dir" in the pear configuration, and the "pman" script into "bin_dir".
By default I believe pear sets the "bin_dir" to something that is already in your $PATH so you should be able to execute "pman strpos" now.
In VIM you need to update the "keywordprg" config (or add it, if it doesn't exists already) to "pman":
set keywordprg=pman
Now open up a .php file, place your cursor over some PHP function and hit "K", you should get the manual page for that function \o/.
Unfortunately Symfony, Zend Framework, Doctrine, and other frameworks/libraries/.. do not distribute unix manual pages yet so I use the Taglist plugin to jump to the code.
Looking forward to when these frameworks start producing unix manual pages, so much easier to read :D
-Hannes
Really nice. Thanks for the hint.
ReplyDeleteCool -- I've added the keywordprg setting to my php.vim ftplugin, and now can have man page lookup that's specific to PHP. /me takes note to figure out how we might do this in ZF...
ReplyDeleteThis is indeed a very nice feature which I will use from this day on...
ReplyDeleteThat's a really nice manual format I didn't know about until now. Thanks for the post. I love the easy integration with Vim, which is my favorite php editor :)
ReplyDeleteCheers,
Jakob
Really would appreciate if you could add a screenshot of vi with the man open.
ReplyDeleteAnon: There isn't much to see, other then a standard manual page.
ReplyDeleteRudy posted some screenshots couple of years ago...:
Thanks for reminding me of this. Newbies with ubuntu should remember to increase PHP memory before installing... :P
ReplyDeletethank you for sharing this tip with us. Though it is available for some time I seem to have missed it while I wanted it.
ReplyDeletesam@sam-desktop:/usr/share/php/PEAR/pman$ sudo pear install doc.php.net/pman
ReplyDeletedownloading pman-1.0.1.tgz ...
Starting to download pman-1.0.1.tgz (3,895,049 bytes)
.....................done: 3,895,049 bytes
sam@sam-desktop:/usr/share/php/PEAR/pman$ pman strpos
The program 'pman' is currently not installed. You can install it by typing:
sudo apt-get install pmtools
pman: command not found
sam@sam-desktop:/usr/share/php/PEAR/pman$
==================
I have this problem when I use pear install under Ubuntu9.10
sam:
ReplyDeleteMake sure the path you get from:
$ pear config-get bin_dir
is in your $PATH
Yes, it is:
ReplyDeletesam@sam-laptop:~$ pear config-get bin_dir
/usr/bin
sam@sam-laptop:~$ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games
More Info:
ReplyDelete==========
sam@sam-laptop:~$ sudo find / -name 'pman';
[sudo] password for sam:
/usr/share/php/PEAR/pman
sam@sam-laptop:~$
Thats.. odd.
ReplyDeleteI assume you have thousands of files under /usr/share/php/PEAR/pman/man3 ?
I just noticed, while reinstalling pman locally, you never get the "install ok: channel://doc.php.net/pman-1.0.1" message.
Try turning on all possible PHP warnings, maybe pear is error out somehwere.
You should have around 6200 files in the pman/man3 directory, plus one executable 'pman'.
This should be a download problem under Ubuntu, My error level setting:
ReplyDeleteerror_reporting = E_ALL
display_errors = On
But I didn't get any error info.
===========
sam@sam-desktop:/usr/share/php/PEAR/pman$ ls -all ./man3/* | wc -l
1900
sam@sam-desktop:/usr/share/php/PEAR/pman
===========
seems like a tar probelm:
cp /build/buildd/php5-5.2.10.dfsg.1/pear-build-download/pman-1.0.1.tgz ~/
cd ~
sudo tar -zxcf pman-1.0.1.tgz
cd pman-1.0.1/
sam@sam-desktop:~/pman-1.0.1$ ls -all
total 276
drwxr-xr-x 3 root root 4096 2010-01-07 10:16 .
drwxr-xr-x 38 sam sam 4096 2010-01-07 10:16 ..
drwxr-xr-x 2 root root 270336 2010-01-07 10:16 man3
-rw-r--r-- 1 sam sam 53 2009-01-08 02:35 pman.sh
sam@sam-desktop:~/pman-1.0.1$ ls -all man3/* | wc -l
6204
I copy all the file to man3 and make a softlike for pman.sh to /usr/bin/, but still can't use 'K' in VIM:
ReplyDelete========
try pman
sam@sam-desktop:/usr/share/php/PEAR/pman$ pman
What manual page do you want?
try VIM:
No manual entry for in_array
shell returned 16
Press ENTER or type command to continue
Does this work?
ReplyDelete$ man -M /usr/share/php/PEAR/pman/ strpos
Did you remember to update your vim binding?
sam@sam-desktop:/usr/share/php/PEAR/pman$ man -M /usr/share/php/PEAR/pman/ strpos
ReplyDeleteNo manual entry for strpos
sam@sam-desktop:/usr/share/php/PEAR/pman/man3$ ls -al *strpos*
-rw-r--r-- 1 root root 841 2010-01-07 10:13 grapheme_strpos.3.gz
-rw-r--r-- 1 root root 820 2010-01-07 10:13 iconv_strpos.3.gz
sam: your download seems broken.
ReplyDeleteTry
$ wget http://doc.php.net/get/pman-1.0.1.tgz
$ pear install pman-1.0.1.tgz
If that doesn't work, send me an email; hannes.magnusson@gmail.com and I'll look better into this.
with the help of
ReplyDelete$ wget http://doc.php.net/get/pman-1.0.1.tgz
$ pear install pman-1.0.1.tgz
I finally find the problem:
Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 8192 bytes) in /usr/share/php/PEAR/Installer.php on line 572
So I modify /etc/php5/cli/php.ini and pman can be installed now.
Awesome, thanks for the tip.
ReplyDeleteI've got all 6204 files in man3 as noted in the earliest test of using the tarball, but a lot of functions that seem to have man pages in that directory are returning "No manual entry for X" from vim. dirname works, for example, but str_replace, get_include_path, set_include_path, in_array, and spl_autoload_register don't. Seems to be any function with an underscore in the name has this problem?
ReplyDeleteElazar:
ReplyDeleteFunction names with underscore work fine for me.
Does
$ pman in_array
work for you?
Does the file "man3/in_array.3.gz" have any content?
Nice Artice
ReplyDeleteAny chance of getting a new build? April 2010 was a long time ago ... thanks!
ReplyDeleteErrr... Very good point Sebastian.
ReplyDeleteWe were looking into how to automatically package and publish pear packages... a year ago...
I don't know what happened to that idea, but we should at the very least publish new unix manpage builds, even if they are created manually, ASAP
-Hannes
Committed a freshly generated function reference (generated by Phd) to a public Git repository for those interested: https://github.com/rbakels/PHP-Documentation
ReplyDeleteNothing fancy, except for a recent build of the PHP documentation :).
The doc.php.net channel doesn't work with pear 1.8.1 on Centos 5.5. Perhaps it is something to do with the HTTP Redirect?
ReplyDeleteI upgraded to 1.9.2 and it worked fine.
@Sam: IIRC the doc.php.net wasn't "installed by default" until PEAR 1.9, so you had to "channel-dicover" it first. The channel itself should work fine with PEAR 1.8 after that (if not, please do file a bug report).
ReplyDelete@Robin: Thanks for the push :)
After your kick-in-the-balls we have now published an up2date unix man pages. It is now available on the doc.php.net channel.
This may be an old post.. but still very relevant, thanks a lot for sharing ( and good-bye php.net/manual/ ^^ ) !
ReplyDelete