On Mar 20, 2010, at 8:00 AM, Robert P. J. Day wrote: > > (my technical editor streak coming to the fore, representing just > some thoughts on reading up to but not including the language > reference so far.) > > * it's not clear what version of PHP the online manual refers to. i > would *guess* that it's the output of a fairly recent build of the > doc trunk, but it wouldn't hurt to make that explicitly clear at the > beginning somewhere.
It includes the build date on the opening page although not the SVN revision it's based on. I vaguely remember someone asking to insert the SVN revision before and a little brain storming on how took place but ... maybe one day. > * not sure if this is covered further into the manual than i've read > so far, but i learned quickly that on some versions of linux (in my > case, fedora), a *lot* of the PHP modules and extensions have been > packages as yum-installable packages. a lot of the PEAR packages as > well. i'm wondering if that's worth mentioning fairly early on for > readers running particular linux distros. A section within install/ that details the situation with linux distributions would probably be useful, as long as it's written to not require frequent updates. There is a section specific to Debian but I don't think every distro needs one... thoughts on making it generic? > * http://www.php.net/manual/en/intro-whatis.php > > "Don't be afraid [of?] reading the long list of PHP's features." > > * http://www.php.net/manual/en/intro-whatcando.php > > "You can make a PHP script to run it without any server or browser." > > - that's a really awkward sentence > > "... extends the feature set adding SimpleXML and XMLReader support." > > - is there a reason to mention XMLReader but not XMLWriter? (what > *is* the state of XML support in PHP these days? must keep > reading.) That section is a bit outdated and easily forgotten. Please file a bug report about this being outdated. Also, we have an online editor that's in alpha stages (beta?) here: https://edit.php.net/ You might want to play with it a bit and create a few patches. After more testing this editor will be publicized and likely linked from each manual page. > * very early on, i might be tempted to have a short section explaining > how readers can examine the current state of PHP on their system, > mostly from the command line. when i was starting out, i was thrilled > to discover "php -m". a short page walking readers through something > like: > > $ php --help > $ php -v > $ php -m > $ php -i > > and so on would probably not hurt, and it's something they could do > with no further background, just to verify that they have a working > and properly-configured PHP setup. Sounds useful, and the command line part was restructured recently so sections like this can be easily found (and pointed to) without getting lost. - http://php.net/manual/features.commandline So early on, this can be referenced. It's difficult to know where a tutorial should go but we lean towards having them within their specific topics, as opposed to being lumped together in the "Getting Started" tutorial. Although there really aren't many tutorials currently, eventually a tutorial index feels useful. > * http://www.php.net/manual/en/configuration.file.php > > - it might be worth telling the reader about "php --ini" here, and > perhaps other ini-related php CLI options. i found the above comment > really useful early on. Sounds like a good idea. Regards, Philip
