php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #31861 The Documentation doesn't describe the language (PHP)
Submitted: 2005-02-06 15:29 UTC Modified: 2005-03-11 16:44 UTC
From: chvol at aol dot com Assigned:
Status: Not a bug Package: Documentation problem
PHP Version: 4.3.10 OS:
Private report: No CVE-ID: None
 [2005-02-06 15:29 UTC] 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?



Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2005-02-24 17:06 UTC] philip@php.net
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-24 19:46 UTC] 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-26 00:27 UTC] derek@php.net
"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-03-11 16:44 UTC] chvol at aol dot com
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.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Fri Apr 19 16:01:27 2024 UTC