Loading ...
Sorry, an error occurred while loading the content.

Re: [php-objects] Re: PEAR DB

Expand Messages
  • Manuel Lemos
    Hello, ... English is not my first language either, but I was told that English is a language, British English is an idiom and American English is another.
    Message 1 of 17 , Jan 1, 2002
    • 0 Attachment
      Hello,

      "Tarique Sani " wrote:
      >
      > On Mon, 31 Dec 2001, Manuel Lemos wrote:
      >
      > > Is it my impression or PHPDoc (AKA JavaDoc) only allows the
      > > documentation to be in one idiom?
      >
      > idiom = language, phrase, saying
      >
      > Well English is not my first language

      English is not my first language either, but I was told that English is
      a language, British English is an idiom and American English is another.
      German is also another idiom but of other language.


      > So I am not sure what you mean by *one idiom* and PHPdoc <> Javadoc there
      > are noteable and several user-friendly enhancements

      What I mean is that PHPdoc only expects documentation within source code
      to be in on idiom. So you can't use PHPdoc to write both English and
      German versions of the documentation of a class.

      Regards,
      Manuel Lemos
    • Jon Frisby
      English is a language. British English is a dialect of English. American English is another dialect of English. German is a language. An idiom is a
      Message 2 of 17 , Jan 1, 2002
      • 0 Attachment
        English is a language. British English is a dialect of English. American
        English is another dialect of English. German is a language.

        An idiom is a colloquial phrase or expression, often having a meaning that
        is significantly divergant from the literal meaning of the words of the
        phrase.

        Some examples of English idioms:
        "Sandblasting a soupcracker" -- (Somewhat uncommon) [V.] A phrase indicating
        that the solution to a problem substantially exceeds the requirements of the
        problem. As in, "Putting a V12 in a Volkswagon Beetle is like sandblasting
        a soupcracker."
        "Take a leak" -- (Common) [V.] Urinate. As in, "I'll be right back, I gotta
        take a leak."
        "Get laid" -- (Common) [V.] Engage in sexual activity. (with a partner. ;>)
        As in, "Jeff is in a good mood today. Did he get laid last night?"

        In programming terms, an idiom is a particular use of a language feature
        that commonly occurs in one language, but does not commonly occur in other
        languages, generally because other languages do not support the feature.
        One such example would be the use closures to implement "undo". This is
        idiomatic to languages that support closures.

        Sorry... Linguistics is a hobby of mine.

        -JF


        -----Original Message-----
        From: mlemos@... [mailto:mlemos@...]On
        Behalf Of Manuel Lemos
        Sent: Tuesday, January 01, 2002 9:35 AM
        To: php-objects@yahoogroups.com
        Subject: Re: [php-objects] Re: PEAR DB


        Hello,

        "Tarique Sani " wrote:
        >
        > On Mon, 31 Dec 2001, Manuel Lemos wrote:
        >
        > > Is it my impression or PHPDoc (AKA JavaDoc) only allows the
        > > documentation to be in one idiom?
        >
        > idiom = language, phrase, saying
        >
        > Well English is not my first language

        English is not my first language either, but I was told that English is
        a language, British English is an idiom and American English is another.
        German is also another idiom but of other language.


        > So I am not sure what you mean by *one idiom* and PHPdoc <> Javadoc
        there
        > are noteable and several user-friendly enhancements

        What I mean is that PHPdoc only expects documentation within source code
        to be in on idiom. So you can't use PHPdoc to write both English and
        German versions of the documentation of a class.

        Regards,
        Manuel Lemos

        Yahoo! Groups Sponsor
        ADVERTISEMENT




        Look here for Free PHP Classes of objects:
        http://phpclasses.UpperDesign.com/
        To unsubscribe from this group, send an email to:
        php-objects-unsubscribe@egroups.com



        Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service.



        [Non-text portions of this message have been removed]
      • Manuel Lemos
        Hello, ... Thanks for the explanation. It doesn t quite match what I understood from what I was told. It is still confusing because language/idiom/dialect
        Message 3 of 17 , Jan 1, 2002
        • 0 Attachment
          Hello,

          Jon Frisby wrote:
          >
          > English is a language. British English is a dialect of English. American
          > English is another dialect of English. German is a language.
          >
          > An idiom is a colloquial phrase or expression, often having a meaning that
          > is significantly divergant from the literal meaning of the words of the
          > phrase.
          >
          > Some examples of English idioms:
          > "Sandblasting a soupcracker" -- (Somewhat uncommon) [V.] A phrase indicating
          > that the solution to a problem substantially exceeds the requirements of the
          > problem. As in, "Putting a V12 in a Volkswagon Beetle is like sandblasting
          > a soupcracker."
          > "Take a leak" -- (Common) [V.] Urinate. As in, "I'll be right back, I gotta
          > take a leak."
          > "Get laid" -- (Common) [V.] Engage in sexual activity. (with a partner. ;>)
          > As in, "Jeff is in a good mood today. Did he get laid last night?"
          >
          > In programming terms, an idiom is a particular use of a language feature
          > that commonly occurs in one language, but does not commonly occur in other
          > languages, generally because other languages do not support the feature.
          > One such example would be the use closures to implement "undo". This is
          > idiomatic to languages that support closures.
          >
          > Sorry... Linguistics is a hobby of mine.

          Thanks for the explanation. It doesn't quite match what I understood
          from what I was told. It is still confusing because
          language/idiom/dialect have similar words in Portuguese
          (lingua/idioma/dialecto) and other latin languages but the real meanings
          are not exactly the same as in English.

          Regards,
          Manuel Lemos
        • Tarique Sani <tarique@sanisoft.com>
          ... Yes - that is correct Hmm... that would be an interesting extension to make. Multilingual PHPdoc!! Not too difficult - will give it a try when I next have
          Message 4 of 17 , Jan 1, 2002
          • 0 Attachment
            On Tue, 1 Jan 2002, Manuel Lemos wrote:

            > What I mean is that PHPdoc only expects documentation within source code
            > to be in on idiom. So you can't use PHPdoc to write both English and
            > German versions of the documentation of a class.

            Yes - that is correct

            Hmm... that would be an interesting extension to make.

            Multilingual PHPdoc!!

            Not too difficult - will give it a try when I next have a couple of hours
            free ...

            Cheers
            Tarique

            --
            ==========================================================
            PHP Applications for E-Biz : http://www.sanisoft.com

            The Ultimate Ghazal Lexicon: http://www.aaina-e-ghazal.com
            ==========================================================
          • Manuel Lemos
            Hello, ... Actually I think people using PHPdoc should drop it for something that uses XML to markup documentation in a more flexible and not so limited way.
            Message 5 of 17 , Jan 1, 2002
            • 0 Attachment
              Hello,

              "Tarique Sani " wrote:
              >
              > On Tue, 1 Jan 2002, Manuel Lemos wrote:
              >
              > > What I mean is that PHPdoc only expects documentation within source code
              > > to be in on idiom. So you can't use PHPdoc to write both English and
              > > German versions of the documentation of a class.
              >
              > Yes - that is correct
              >
              > Hmm... that would be an interesting extension to make.
              >
              > Multilingual PHPdoc!!
              >
              > Not too difficult - will give it a try when I next have a couple of hours
              > free ...

              Actually I think people using PHPdoc should drop it for something that
              uses XML to markup documentation in a more flexible and not so limited
              way. Parsing PHPdoc is not as easy as parsing XML. So when you want to
              add a new markup is much harder than adding support to a new XML tag.

              In MetaL I have used extra tags to document classes using
              <documentation></documentation> markup wherever I need: functions,
              arguments, variables and even example code. Each documentation section
              is tagged with a idiom property, so I can have multiple documentation
              sections for each of the class elements, one for each idiom. The
              documentation extraction process extracts the appropriate documentation
              sections for the selected idiom.

              The result is a full hyperlinked document. You may see one here after
              being filtered into HTML:

              http://phpclasses.upperdesign.com/browse.html/package/250

              Since this is meta-programming, I don't need to stuff the generated PHP
              code for the class with any PHPdoc or whatever like tags.

              Anyway, if you use a XML based syntax for describing documentation data,
              it is much easier to process and extend when you want to support more
              documentation tags, like one for specifying the idiom.

              Regards,
              Manuel Lemos
            • Tarique Sani <tarique@sanisoft.com>
              ... Hmm... ... For me the advantage of having a PHPdoc tool is to have the comments and documentation in the code file itself. And I keep adding the
              Message 6 of 17 , Jan 1, 2002
              • 0 Attachment
                On Wed, 2 Jan 2002, Manuel Lemos wrote:

                > Since this is meta-programming, I don't need to stuff the generated PHP
                > code for the class with any PHPdoc or whatever like tags.

                Hmm... ... For me the advantage of having a PHPdoc tool is to have
                the comments and documentation in the code file itself. And I keep adding
                the documention as I write the code.

                I don't think PHPdoc / Javadoc is meant to replace complete documentation
                OR document generation - for that I use DocBook :-)

                Cheers

                Tarique


                --
                ==========================================================
                PHP Applications for E-Biz : http://www.sanisoft.com

                The Ultimate Ghazal Lexicon: http://www.aaina-e-ghazal.com
                ==========================================================
              • Manuel Lemos
                Hello, ... I was not telling you to put documention in separate XML files, but rather use XML within the code file comments instead of PHPdoc tags. Regards,
                Message 7 of 17 , Jan 1, 2002
                • 0 Attachment
                  Hello,

                  "Tarique Sani " wrote:
                  >
                  > On Wed, 2 Jan 2002, Manuel Lemos wrote:
                  >
                  > > Since this is meta-programming, I don't need to stuff the generated PHP
                  > > code for the class with any PHPdoc or whatever like tags.
                  >
                  > Hmm... ... For me the advantage of having a PHPdoc tool is to have
                  > the comments and documentation in the code file itself. And I keep adding
                  > the documention as I write the code.
                  >
                  > I don't think PHPdoc / Javadoc is meant to replace complete documentation
                  > OR document generation - for that I use DocBook :-)

                  I was not telling you to put documention in separate XML files, but
                  rather use XML within the code file comments instead of PHPdoc tags.

                  Regards,
                  Manuel Lemos
                • Tarique Sani <tarique@sanisoft.com>
                  ... Oops! time to get further caffineated :-) Have downloaded the XML writer class Will experiment Thanks a lot! Tarique --
                  Message 8 of 17 , Jan 2, 2002
                  • 0 Attachment
                    On Wed, 2 Jan 2002, Manuel Lemos wrote:

                    > I was not telling you to put documention in separate XML files, but
                    > rather use XML within the code file comments instead of PHPdoc tags.

                    Oops! time to get further caffineated :-)

                    Have downloaded the XML writer class

                    Will experiment

                    Thanks a lot!

                    Tarique

                    --
                    ==========================================================
                    PHP Applications for E-Biz : http://www.sanisoft.com

                    The Ultimate Ghazal Lexicon: http://www.aaina-e-ghazal.com
                    ==========================================================
                  • sqldreamer
                    ... Hi, do you mean something like this? ... /* doSomething public integer
                    Message 9 of 17 , Jan 2, 2002
                    • 0 Attachment
                      > I was not telling you to put documention in separate XML files, but
                      > rather use XML within the code file comments instead of PHPdoc tags.
                      >

                      Hi,

                      do you mean something like this?

                      ...
                      /*
                      <documentation>
                      <function>doSomething</function>
                      <access>public</access>
                      <return>integer</return>
                      <description>abcdef</description>
                      </documentation>
                      */
                      function doSomething(){
                      ...

                      So you will parse the php-file ('xmlwriterclass.php') and extract all
                      xml-tags for an extra document ('xmlwriterclass.html')?
                      But finally you removed the XML-tags from 'xmlwriterclass.php'

                      ThankX
                    • Jon Frisby
                      Such differences between language can be disconcerting at first... If you think the dichotomy between meanings in Portuguese and English is large, you should
                      Message 10 of 17 , Jan 2, 2002
                      • 0 Attachment
                        Such differences between language can be disconcerting at first... If you
                        think the dichotomy between meanings in Portuguese and English is large, you
                        should compare Japanese and English. Wow. They are truly alien
                        languages... One cannot simply "translate" between them. Beyond
                        differences in the meanings of words, in Japanese one simply uses different
                        words for the same situation. ("I'm hungry" in English would be stated as
                        "My stomach has become empty" in Japanese...)

                        -JF
                        -----Original Message-----
                        From: mlemos@... [mailto:mlemos@...]On
                        Behalf Of Manuel Lemos
                        Sent: Tuesday, January 01, 2002 4:36 PM
                        To: php-objects@yahoogroups.com
                        Cc: mlemos@...
                        Subject: Re: [php-objects] Re: PEAR DB


                        Hello,

                        Jon Frisby wrote:
                        >
                        > English is a language. British English is a dialect of English.
                        American
                        > English is another dialect of English. German is a language.
                        >
                        > An idiom is a colloquial phrase or expression, often having a meaning
                        that
                        > is significantly divergant from the literal meaning of the words of the
                        > phrase.
                        >
                        > Some examples of English idioms:
                        > "Sandblasting a soupcracker" -- (Somewhat uncommon) [V.] A phrase
                        indicating
                        > that the solution to a problem substantially exceeds the requirements of
                        the
                        > problem. As in, "Putting a V12 in a Volkswagon Beetle is like
                        sandblasting
                        > a soupcracker."
                        > "Take a leak" -- (Common) [V.] Urinate. As in, "I'll be right back, I
                        gotta
                        > take a leak."
                        > "Get laid" -- (Common) [V.] Engage in sexual activity. (with a partner.
                        ;>)
                        > As in, "Jeff is in a good mood today. Did he get laid last night?"
                        >
                        > In programming terms, an idiom is a particular use of a language feature
                        > that commonly occurs in one language, but does not commonly occur in
                        other
                        > languages, generally because other languages do not support the feature.
                        > One such example would be the use closures to implement "undo". This is
                        > idiomatic to languages that support closures.
                        >
                        > Sorry... Linguistics is a hobby of mine.

                        Thanks for the explanation. It doesn't quite match what I understood
                        from what I was told. It is still confusing because
                        language/idiom/dialect have similar words in Portuguese
                        (lingua/idioma/dialecto) and other latin languages but the real meanings
                        are not exactly the same as in English.

                        Regards,
                        Manuel Lemos

                        Yahoo! Groups Sponsor
                        ADVERTISEMENT




                        Look here for Free PHP Classes of objects:
                        http://phpclasses.UpperDesign.com/
                        To unsubscribe from this group, send an email to:
                        php-objects-unsubscribe@egroups.com



                        Your use of Yahoo! Groups is subject to the Yahoo! Terms of Service.



                        [Non-text portions of this message have been removed]
                      • Manuel Lemos
                        Hello, ... Yes, a lot of Brazilian people still insist on translating English to Portuguese word by word, which does not seem right but it is simple for them
                        Message 11 of 17 , Jan 2, 2002
                        • 0 Attachment
                          Hello,

                          Jon Frisby wrote:
                          >
                          > Such differences between language can be disconcerting at first... If you
                          > think the dichotomy between meanings in Portuguese and English is large, you
                          > should compare Japanese and English. Wow. They are truly alien
                          > languages... One cannot simply "translate" between them. Beyond
                          > differences in the meanings of words, in Japanese one simply uses different
                          > words for the same situation. ("I'm hungry" in English would be stated as
                          > "My stomach has become empty" in Japanese...)

                          Yes, a lot of Brazilian people still insist on translating English to
                          Portuguese word by word, which does not seem right but it is simple for
                          them when they don't know the foreign language very well.

                          Anyway, this thread has now gone way off-topic. Please reply privately
                          if you still have anything to say about it.

                          Regards,
                          Manuel Lemos
                        • Manuel Lemos
                          Hello, ... yes, although some of your example properties already exist in MetaL class function declaration as MetaL classes source code is XML already. ... No,
                          Message 12 of 17 , Jan 2, 2002
                          • 0 Attachment
                            Hello,

                            sqldreamer wrote:
                            >
                            > > I was not telling you to put documention in separate XML files, but
                            > > rather use XML within the code file comments instead of PHPdoc tags.
                            > >
                            >
                            > Hi,
                            >
                            > do you mean something like this?
                            >
                            > ...
                            > /*
                            > <documentation>
                            > <function>doSomething</function>
                            > <access>public</access>
                            > <return>integer</return>
                            > <description>abcdef</description>
                            > </documentation>
                            > */
                            > function doSomething(){
                            > ...

                            yes, although some of your example properties already exist in MetaL
                            class function declaration as MetaL classes source code is XML already.


                            > So you will parse the php-file ('xmlwriterclass.php') and extract all
                            > xml-tags for an extra document ('xmlwriterclass.html')?
                            > But finally you removed the XML-tags from 'xmlwriterclass.php'

                            No, MetaL compiler generates the PHP and HTML files from MetaL source
                            code in XML, so the generated PHP code never shows any documentation in
                            comments. Here is a sample MetaL source code:




























                            Are you ready? This may look scary! :-)
















































                            Ok, here it is. :-)

                            <function>
                            <name>encodedata</name>
                            <type>BOOLEAN</type>
                            <protected />
                            <documentation>
                            <idiom>en</idiom>
                            <purpose>Encodes text in a suitable form for outputting as XML
                            data
                            parts or tag attributes.</purpose>
                            <usage>Pass text data in the encoding type defined by the
                            <variablelink>inputencoding</variablelink> variable and expect
                            the
                            encoded result in the encoding type defined by the
                            <variablelink>outputencoding</variablelink> variable.</usage>
                            <returnvalue>Success boolean flag. If this flag is
                            <tt><booleanvalue>0</booleanvalue></tt> then the
                            <variablelink>error</variablelink> variable contains the error
                            message that explains the failure.</returnvalue>
                            </documentation>
                            <argument>
                            <name>data</name>
                            <type>STRING</type>
                            <documentation>
                            <idiom>en</idiom>
                            <purpose>Input text data in the encoding type defined by the
                            <variablelink>inputencoding</variablelink> variable.</purpose>
                            </documentation>
                            </argument>
                            <argument>
                            <name>encodeddata</name>
                            <type>STRING</type>
                            <out />
                            <documentation>
                            <idiom>en</idiom>
                            <purpose>Encoded result data in the encoding type defined by the
                            <variablelink>outputencoding</variablelink> variable.</purpose>
                            </documentation>
                            </argument>
                            <do>
                            <if>
                            <istrue>
                            <this>inputencoding</this> <equalstrings />
                            <this>outputencoding</this>
                            </istrue>
                            <then>
                            <setbuffer>
                            <argument>encodeddata</argument>
                            <callthis>
                            <function>escapedata</function>
                            <arguments>
                            <data><argument>data</argument></data>
                            </arguments>
                            </callthis>
                            </setbuffer>
                            </then>
                            <else>
                            <switch>

                            <value><lowercase><this>outputencoding</this></lowercase></value>

                            <case>
                            <value>utf-8</value>
                            <do>
                            <if>
                            <istrue>
                            <lowercase><this>inputencoding</this></lowercase>
                            <equalstrings /> <string>iso-8859-1</string>
                            </istrue>
                            <then>
                            <utf8encode>
                            <data><callthis>
                            <function>escapedata</function>
                            <arguments>
                            <data><argument>data</argument></data>
                            </arguments>
                            </callthis></data>

                            <encoded><stringvariable>encoded_data</stringvariable></encoded>
                            </utf8encode>
                            <setbuffer>
                            <argument>encodeddata</argument>
                            <variable>encoded_data</variable>
                            </setbuffer>
                            </then>
                            <else>
                            <set>
                            <this>error</this>
                            <group>
                            <string>can not encode iso-8859-1 data in </string>
                            <join />
                            <this>outputencoding</this>
                            </group>
                            </set>
                            <return><false /></return>
                            </else>
                            </if>
                            <break />
                            </do>
                            </case>

                            <case>
                            <value>iso-8859-1</value>
                            <do>
                            <if>
                            <istrue>
                            <lowercase><this>inputencoding</this></lowercase>
                            <equalstrings /> <string>utf-8</string>
                            </istrue>
                            <then>
                            <utf8decode>

                            <decoded><stringvariable>decoded</stringvariable></decoded>
                            <data><argument>data</argument></data>
                            </utf8decode>
                            <setbuffer>
                            <argument>encodeddata</argument>
                            <callthis>
                            <function>escapedata</function>
                            <arguments>
                            <data><variable>decoded</variable></data>
                            </arguments>
                            </callthis>
                            </setbuffer>
                            </then>
                            <else>
                            <set>
                            <this>error</this>
                            <group>
                            <string>can not encode utf-8 data in </string>
                            <join />
                            <this>outputencoding</this>
                            </group>
                            </set>
                            <return><false /></return>
                            </else>
                            </if>
                            <break />
                            </do>
                            </case>

                            <default>
                            <do>
                            <set>
                            <this>error</this>
                            <group>
                            <string>can not encode data in </string>
                            <join />
                            <this>inputencoding</this>
                            </group>
                            </set>
                            <return><false /></return>
                            </do>
                            </default>

                            </switch>

                            </else>
                            </if>
                            <return><true /></return>
                            </do>
                            </function>
                          Your message has been successfully submitted and would be delivered to recipients shortly.