ID: 31861
User updated by: chvol at aol dot com
Reported By: chvol at aol dot com
Status: Bogus
Bug Type: Documentation problem
PHP Version: 4.3.10
New Comment:
The section on Instruction Separation is missing a definition of the
general format of an Instruction. From my limited experience, it can
be at least any of the following:
1. An expression that is merely evaluated. Side-effects such as output
(HTML) and database (SQL) changes are the result.
2. A command plus one argument. (Refer to the types of commands and
the list)
3. { and }
4. What else is there that I don't know?
I'm not sure why the responses from the very beginning have included
questions as to what I mean, but at the same time declared my point to
be "Bogus" without the benefit of knowledge of my answers first.
Previous Comments:
------------------------------------------------------------------------
[2005-02-26 00:27:18] [EMAIL PROTECTED]
"Imagine trying to learn PHP by reading through that document. But
all
you need is to add that high level description and it would be useful
to
lots more people."
When people ask what to read to 'learn PHP', we tell them to read the
first three chapters of the manual. If you're trying to learn where
certain constructs should be used, you should read through the language
reference section, php.net/langref. This seems to be a misunderstanding
on your part, and not a fault of the documentation itself.
"But the user isn't supposed to
have to look through the entire manual to find one item: a certain
command."
The manual has excellent search facilities, and if you know what you're
looking for you can use php.net/[search term here] as in: php.net/xml
for the xml extension documentation, and php.net/xml_parser_create for
the documentation of that function.
------------------------------------------------------------------------
[2005-02-24 19:46:13] chvol at aol dot com
"I don't understand what you're asking for here, or the problem. PHP is
huge so the information is broken down into appropriate sections."
That is the lower level detail of each type of construct. I am talking
about the higher level question: "What constructs can be here?". You
have no "grammar" (No, it need not be formal. Just something that
gives the overall structure of a script/program/file down to the
detail.)
"Want to learn about for?"
No, I want to know what can be at some point (construct) in a line.
Just make sure the description includes the possibility of a FOR
occurring there. I am not talking about your description "not allowing
a FOR", but rather the missing high level description of the language
would at some level refer to FOR. The details might even stay where
they are now, actually.
"Read about loops. Echo is documented in several places. All "commands"
are described as per their extension, or section (like language
reference). The search feature can be useful as well."
That's for people who already know the language and even the command
that they need, but are only unsure of some aspect. My question is
what can occur in general at each logical point (within each type of
construct) at the script and line level.
"If everything was on one page, that page would be enormous. Maybe you
should download the HTML one-page version of the manual."
I'm not talking about the pages it is on, really. The problem is that
that form of the information is missing. If you'd like, I could show
you how to do it with a small subset of PHP.
Imagine trying to learn PHP by reading through that document. But all
you need is to add that high level description and it would be useful
to lots more people. That small extra piece would make the document
much more useful.
------------------------------------------------------------------------
[2005-02-24 17:06:33] [EMAIL PROTECTED]
I don't understand what you're asking for here, or the problem. PHP is
huge so the information is broken down into appropriate sections. Want
to learn about for? Read about loops. Echo is documented in several
places. All "commands" are described as per their extension, or section
(like language reference). The search feature can be useful as well.
If everything was on one page, that page would be enormous. Maybe you
should download the HTML one-page version of the manual.
------------------------------------------------------------------------
[2005-02-06 15:29:16] chvol at aol dot com
Description:
------------
This documentation doesn't explain the PHP language. It gives low
level constructs, and various categories where certain things can be
found. However, it doesn't actually simply define the language itself:
a line consists of statements separated by ";". Each statement consists
of one of the following: MISSING LIST HERE
If you poke around you can find reference to the FOR command in one
place, and ECHO somewhere else in there. But the user isn't supposed
to have to look through the entire manual to find one item: a certain
command. I have been trying to find one particular command and have
been searching through the different sections.
Why don't you just list them out? You know, describe the PHP language
commands?
------------------------------------------------------------------------
--
Edit this bug report at http://bugs.php.net/?id=31861&edit=1
