FAQ
From: chvol at aol dot com
Operating system:
PHP version: 4.3.10
PHP Bug Type: Documentation problem
Bug description: The Documentation doesn't describe the language (PHP)

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?

Search Discussions

  • Chvol at aol dot com at Feb 25, 2005 at 3:54 pm
    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:

    "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.


    Previous Comments:
    ------------------------------------------------------------------------

    [2005-02-24 17:06:33] 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-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
  • Philip at Feb 25, 2005 at 3:55 pm
    ID: 31861
    Updated by: philip@php.net
    Reported By: chvol at aol dot com
    -Status: Open
    +Status: Bogus
    Bug Type: Documentation problem
    PHP Version: 4.3.10
    New Comment:

    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.


    Previous Comments:
    ------------------------------------------------------------------------

    [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
  • Derek at Feb 26, 2005 at 12:09 am
    ID: 31861
    Updated by: derek@php.net
    Reported By: chvol at aol dot com
    Status: Bogus
    Bug Type: Documentation problem
    PHP Version: 4.3.10
    New Comment:

    "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.


    Previous Comments:
    ------------------------------------------------------------------------

    [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] 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-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
  • Sveta Smirnova at Feb 27, 2005 at 1:01 pm

    derek@php.net wrote:

    ID: 31861
    Updated by: derek@php.net
    Reported By: chvol at aol dot com
    Status: Bogus
    Bug Type: Documentation problem
    PHP Version: 4.3.10
    New Comment:

    "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.


    Previous Comments:
    ------------------------------------------------------------------------

    [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] 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-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?




    ------------------------------------------------------------------------
    Dears!

    I am sorry, but I think, I should comment it.

    I think it is problem. And not only for people who just start to learn PHP.
    My experience as illustration :-)
    I am using cable modem, so I can't use allways excellent search
    facilities in php.net website. But I have local copy of manual.
    Sometimes I need to find point description of language constructs. (New
    'instance of', for example.) For function in manual there is good
    reference, but not for language constructs and it is true: very
    difficult to find they. (Try to find 'instance of' or ternary operator:
    it is not intuitive.)

    If you agree, I can try to make such reference.

    Kind regards,
    member of phpdoc-ru translation team,
    Sveta Smirnova.

    --
    S uvazheniem, Sveta Smirnova
    Best regards, sorry for English, Sveta Smirnova
    mailto:sveta@microbecal.com
  • Chvol at aol dot com at Mar 11, 2005 at 3:44 pm
    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] 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-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] 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-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

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupphp-doc @
categoriesphp
postedFeb 6, '05 at 2:29p
activeMar 11, '05 at 3:44p
posts6
users4
websitedoc.php.net

People

Translate

site design / logo © 2018 Grokbase