cvs: peardoc /en/package/console/console-commandline creating-the-parser.xml populating-the-parser.xml /entities global.ent
| From: | Christian Weiske | Date: | Fri, 07 Nov 2008 18:38:17 +0000 |
| Subject: | cvs: peardoc /en/package/console/console-commandline creating-the-parser.xml populating-the-parser.xml /entities global.ent | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-11250@lists.php.net to get a copy of this message | ||
cweiske Fri Nov 7 18:38:17 2008 UTC
Modified files:
/peardoc/entities global.ent
/peardoc/en/package/console/console-commandline
creating-the-parser.xml
populating-the-parser.xml
Log:
Use new <phd:pearapi> to link to docs
http://cvs.php.net/viewvc.cgi/peardoc/entities/global.ent?r1=1.3&r2=1.4&diff_format=u Index: peardoc/entities/global.ent diff -u peardoc/entities/global.ent:1.3 peardoc/entities/global.ent:1.4 --- peardoc/entities/global.ent:1.3 Mon Oct 20 15:40:42 2008 +++ peardoc/entities/global.ent Fri Nov 7 18:38:17 2008 @@ -1,6 +1,6 @@ <!-- -*- SGML -*- - $Id: global.ent,v 1.3 2008/10/20 15:40:42 gauthierm Exp $ + $Id: global.ent,v 1.4 2008/11/07 18:38:17 cweiske Exp $ Contains global "macros" for all the XML documents. @@ -272,7 +272,6 @@ <!-- For links to the API documentation generated by phpdocumentor --> <!ENTITY phpdocbase.html-page2 "http://pear.php.net/package/HTML_Page2/docs/latest/HTML_Page2/HTML_Page2.html#method"> <!ENTITY phpdocbase.console-color "http://pear.php.net/package/Console_Color/docs/latest/Console_Color/Console_Color.html#method"> -<!ENTITY phpdocbase.console-commandline "http://pear.php.net/package/Console_CommandLine/docs/latest/Console_CommandLine/Console_CommandLine.html#method"> <!ENTITY phpdocbase.console-progressbar "http://pear.php.net/package/Console_ProgressBar/docs/latest/Console_ProgressBar/Console_ProgressBar.html#method"> <!ENTITY phpdocbase.datetime-date "http://pear.php.net/package/Date/docs/latest/Date/Date.html"> <!ENTITY phpdocbase.datetime-date.method "http://pear.php.net/package/Date/docs/latest/Date/Date.html#class_methods"> http://cvs.php.net/viewvc.cgi/peardoc/en/package/console/console-commandline/creating-the-parser.xml?r1=1.6&r2=1.7&diff_format=u Index: peardoc/en/package/console/console-commandline/creating-the-parser.xml diff -u peardoc/en/package/console/console-commandline/creating-the-parser.xml:1.6 peardoc/en/package/console/console-commandline/creating-the-parser.xml:1.7 --- peardoc/en/package/console/console-commandline/creating-the-parser.xml:1.6 Thu Oct 9 15:16:21 2008 +++ peardoc/en/package/console/console-commandline/creating-the-parser.xml Fri Nov 7 18:38:17 2008 @@ -1,5 +1,9 @@ <?xml version="1.0" encoding="utf-8"?> -<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.console.console-commandline.creating-the-parser"> +<refentry + xmlns="http://docbook.org/ns/docbook" + xmlns:phd="http://www.php.net/ns/phd" + version="lillet" xml:id="package.console.console-commandline.creating-the-parser" +> <refnamediv> <refname>Creating the parser</refname> <refpurpose> @@ -8,8 +12,8 @@ </refpurpose> </refnamediv> <refsection xml:id="package.console.console-commandline.creating-the-parser.intro"><info><title><classname>Console_CommandLine</classname> constructor</title></info> - - <para><classname>Console_CommandLine</classname> constructor takes an + + <para><classname>Console_CommandLine</classname> constructor takes an optional array of parameters explained in the table below. Note that if you are using an <acronym>XML</acronym> definition file, you can pass these parameters in it (see <acronym>XML</acronym> example for @@ -17,7 +21,7 @@ </para> <para> <table><title>Available parameters</title> - + <tgroup cols="4"> <thead> <row> @@ -38,13 +42,13 @@ <entry>description</entry> <entry>string</entry> <entry>no, but recommended for the help message</entry> - <entry>the description of your program: this should explain what + <entry>the description of your program: this should explain what your program is supposed to do</entry> </row> <row> <entry>version</entry> <entry>mixed (string or numeric)</entry> - <entry>no, note that if not given, the --version option will + <entry>no, note that if not given, the --version option will not be available</entry> <entry>the program version number</entry> </row> @@ -52,22 +56,22 @@ <entry>add_help_option</entry> <entry>boolean</entry> <entry>no, default to &true;</entry> - <entry>if set to &false; the parser will not generate + <entry>if set to &false; the parser will not generate automatically the <quote>help</quote> option</entry> </row> <row> <entry>add_version_option</entry> <entry>boolean</entry> <entry>no, default to &true;</entry> - <entry>if set to &false; the parser will not generate + <entry>if set to &false; the parser will not generate automatically the <quote>version</quote> option</entry> </row> <row> <entry>force_posix</entry> <entry>boolean</entry> <entry>no, default to &false;</entry> - <entry>if set to &true;, the parser will force - <acronym>POSIX</acronym> compliance (please see the gettext + <entry>if set to &true;, the parser will force + <acronym>POSIX</acronym> compliance (please see the gettext manual for more information)</entry> </row> </tbody> @@ -76,14 +80,14 @@ </para> </refsection> <refsection xml:id="package.console.console-commandline.creating-the-parser.php"><info><title>Using <acronym>PHP</acronym> code</title></info> - + <para>The examples below demonstrate how to instanciate <classname>Console_CommandLine</classname> and build a parser using <acronym>PHP</acronym> code. </para> <para> <example><info><title>The simplest way</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -99,7 +103,7 @@ </para> <para> <example><info><title>Alternative method</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -114,14 +118,14 @@ </para> </refsection> <refsection xml:id="package.console.console-commandline.creating-the-parser.xml"><info><title>Using an <acronym>XML</acronym> definition file</title></info> - + <para>The examples below demonstrate how to instanciate <classname>Console_CommandLine</classname> and build a parser using an - <acronym>XML</acronym> definition file, this can be very useful if you - have a big program or if you need to reuse your user interface settings + <acronym>XML</acronym> definition file, this can be very useful if you + have a big program or if you need to reuse your user interface settings for a web frontend for example. <example><info><title>The <acronym>XML</acronym> file</title></info> - + <programlisting role="xml"> <![CDATA[ <?xml version="1.0" encoding="utf-8" standalone="yes"?> @@ -135,7 +139,7 @@ </para> <para> <example><info><title>The <acronym>PHP</acronym> file</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -146,12 +150,15 @@ </programlisting> </example> </para> - <para> - Note: Using and <acronym>XML</acronym> string you would have called - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;fromXmlString"> - <function>fromXmlString()</function></link> instead of - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;fromXmlFile"> - <function>fromXmlFile()</function></link> of course. - </para> + + <note> + <para> + Using an <acronym>XML</acronym> string you would have called + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::fromXmlString">fromXmlString</phd:pearapi> + instead of + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::fromXmlFile">fromXmlFile</phd:pearapi> + of course. + </para> + </note> </refsection> </refentry> http://cvs.php.net/viewvc.cgi/peardoc/en/package/console/console-commandline/populating-the-parser.xml?r1=1.5&r2=1.6&diff_format=u Index: peardoc/en/package/console/console-commandline/populating-the-parser.xml diff -u peardoc/en/package/console/console-commandline/populating-the-parser.xml:1.5 peardoc/en/package/console/console-commandline/populating-the-parser.xml:1.6 --- peardoc/en/package/console/console-commandline/populating-the-parser.xml:1.5 Thu Oct 9 15:16:21 2008 +++ peardoc/en/package/console/console-commandline/populating-the-parser.xml Fri Nov 7 18:38:17 2008 @@ -1,5 +1,10 @@ <?xml version="1.0" encoding="utf-8"?> -<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.console.console-commandline.populating-the-parser"> +<refentry + xmlns="http://docbook.org/ns/docbook" + xmlns:phd="http://www.php.net/ns/phd" + version="lillet" + xml:id="package.console.console-commandline.populating-the-parser" +> <refnamediv> <refname>Populating the parser</refname> <refpurpose> @@ -7,9 +12,9 @@ </refpurpose> </refnamediv> <refsection xml:id="package.console.console-commandline.populating-the-parser.options"><info><title>Adding options</title></info> - + <refsection xml:id="package.console.console-commandline.populating-the-parser.options.background"><info><title>Some background</title></info> - + <para> Options are used to provide extra information to tune or customize the execution of a program. In case it wasn't clear, options are usually @@ -49,17 +54,17 @@ </para> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.options.adding"><info><title>Adding options with <classname>Console_CommandLine</classname></title></info> - + <para> To add options to your parser, just create the parser as explained in the - previous section and use the - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;addOption"> - <function>Console_CommandLine::addOption</function></link> method. + previous section and use the + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::addOption"/> + method. </para> <para> - The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;addOption"> - <function>Console_CommandLine::addOption</function></link> method takes - two arguments: + The + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::addOption"/> + method takes two arguments: <itemizedlist> <listitem> <simpara>the option name: a string that will be used to access the @@ -73,7 +78,7 @@ </listitem> </itemizedlist> <table><title>Available option parameters</title> - + <tgroup cols="5"> <thead> <row> @@ -132,7 +137,7 @@ <entry>string</entry> <entry>no, if not given it will default to the option name</entry> <entry>the name to display in the option help line</entry> - <entry>page_orientation (the help ligne will be: + <entry>page_orientation (the help ligne will be: --orientation=page_orientation)</entry> </row> </tbody> @@ -141,7 +146,7 @@ </para> <para> <example><info><title>Adding commandline options</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -151,7 +156,7 @@ 'version' => '0.0.1', // the version of your program )); -// Adding a simple option that takes no argument and that tell our program to +// Adding a simple option that takes no argument and that tell our program to // turn on verbose output: $parser->addOption( 'verbose', @@ -211,22 +216,22 @@ ( [verbose] => 1 [orientation] => rtl - [help] => - [version] => + [help] => + [version] => ) ]]> </programlisting> </para> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.options.actions"><info><title>Options actions</title></info> - + <para> Actions tell the parser how to handle option values, among other things they tell the parser if the option expects a value or not and how to store this value in the result object. </para> <refsection><info><title>StoreTrue</title></info> - + <para>This action tells the parser to store the value true in the result object if the option is present in the command line, for example: @@ -250,7 +255,7 @@ </para> </refsection> <refsection><info><title>StoreFalse</title></info> - + <para>This action tells the parser to store the value false in the result object if the option is present in the command line, for example:</para> @@ -273,14 +278,14 @@ </para> </refsection> <refsection><info><title>StoreString</title></info> - + <para>This action tells the parser that the option expects a value and to store this value as an integer in the result object, for example:</para> <para> <programlisting role="text">$ <yourprogram> -o out.txt</programlisting> </para> <para> - will store the string <quote>out.txt</quote> in + will store the string <quote>out.txt</quote> in <varname>$result->options['outfile']</varname>, assuming the option was defined like this: </para> @@ -296,7 +301,7 @@ </para> </refsection> <refsection><info><title>StoreInt</title></info> - + <para>This action tells the parser that the option expects a value and to store this value as an integer in the result object, for example:</para> <para> @@ -318,7 +323,7 @@ </para> </refsection> <refsection><info><title>StoreFloat</title></info> - + <para>This action tells the parser that the option expects a value and to store this value as a float in the result object, for example:</para> <para> @@ -340,9 +345,9 @@ </para> </refsection> <refsection><info><title>Counter</title></info> - + <para>This action tells the parser to increment the value in the result - object each time it encounters the option in the command line, for + object each time it encounters the option in the command line, for example:</para> <para> <programlisting role="text">$ <yourprogram> -vvvv</programlisting> @@ -372,22 +377,22 @@ </para> </refsection> <refsection><info><title>Help</title></info> - + <para>This action tells the parser to display the help message if it encounters the option in the command line, most of the time you won't need this since it is handled by Console_CommandLine internally.</para> </refsection> <refsection><info><title>Version</title></info> - + <para>This action tells the parser to display the program version if it encounters the option in the command line, as for Help action, chances - are that you won't need this since it is handled by + are that you won't need this since it is handled by Console_CommandLine internally.</para> </refsection> <refsection><info><title>Password</title></info> - + <para>This action allows the user to either type the password on the - commandline or to be prompted for it (will not echo on unix systems), + commandline or to be prompted for it (will not echo on unix systems), some examples:</para> <para> <programlisting role="php"> @@ -417,24 +422,24 @@ </para> </refsection> <refsection><info><title>Callback</title></info> - - <para>This action allows to specify a <acronym>PHP</acronym> callback - to handle user input. The callback must be a php callable and must + + <para>This action allows to specify a <acronym>PHP</acronym> callback + to handle user input. The callback must be a php callable and must accept five arguments:</para> <itemizedlist> <listitem> <simpara>the value of the option;</simpara> </listitem> <listitem> - <simpara>the + <simpara>the <classname>Console_CommandLine_Option_Callback</classname> instance</simpara> </listitem> <listitem> - <simpara>the + <simpara>the <classname>Console_CommandLine_Result</classname> instance</simpara> </listitem> <listitem> - <simpara>the + <simpara>the <classname>Console_CommandLine</classname> instance (the parser).</simpara> </listitem> <listitem> @@ -501,9 +506,9 @@ </refsection> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.arguments"><info><title>Adding arguments</title></info> - + <refsection xml:id="package.console.console-commandline.populating-the-parser.arguments.background"><info><title>Some background</title></info> - + <para> Arguments are for those pieces of information that your program absolutely, positively requires to run. @@ -525,18 +530,17 @@ </para> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.arguments.adding"><info><title>Adding arguments with <classname>Console_CommandLine</classname></title></info> - + <para> To add arguments to your parser, just create the parser as explained in - the previous section and use the - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;addArgument"> - <function>Console_CommandLine::addArgument</function></link> + the previous section and use the + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::addArgument"/> method. </para> <para> - The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;addArgument"> - <function>Console_CommandLine::addArgument</function></link> - method takes two arguments: + The + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::addArgument"/> + method takes two arguments: <itemizedlist> <listitem> <simpara>the argument name: a string that will be used to access the @@ -545,14 +549,14 @@ <varname>$result->args['foo']</varname>;</simpara> </listitem> <listitem> - <simpara>the arguments parameters: an array of various informations + <simpara>the arguments parameters: an array of various informations as explained below.</simpara> </listitem> </itemizedlist> </para> <para> <table><title>Available arguments parameters</title> - + <tgroup cols="5"> <thead> <row> @@ -591,7 +595,7 @@ </para> <para> <example><info><title>Adding commandline arguments</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -643,16 +647,16 @@ </refsection> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.subcommands"><info><title>Adding sub-commands</title></info> - + <refsection xml:id="package.console.console-commandline.populating-the-parser.subcommands.background"><info><title>What are sub-commands ?</title></info> - + <para> Some programs are very complex, you can't do anything about that but you need to provide the best user interface possible in order to have happy users. In some cases, sub-commands can be very useful, take the PEAR installer for example, it is much more clearer to separate the installer functionalities than to mix all functionalities in the same - interface, that's why you have an interface like: + interface, that's why you have an interface like: </para> <programlisting role="text"> <![CDATA[ @@ -663,7 +667,7 @@ </programlisting> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.subcommands.adding"><info><title>Adding sub-commands with <classname>Console_CommandLine</classname></title></info> - + <para>TODO: develop this section</para> </refsection> </refsection>
http://cvs.php.net/viewvc.cgi/peardoc/entities/global.ent?r1=1.3&r2=1.4&diff_format=u Index: peardoc/entities/global.ent diff -u peardoc/entities/global.ent:1.3 peardoc/entities/global.ent:1.4 --- peardoc/entities/global.ent:1.3 Mon Oct 20 15:40:42 2008 +++ peardoc/entities/global.ent Fri Nov 7 18:38:17 2008 @@ -1,6 +1,6 @@ <!-- -*- SGML -*- - $Id: global.ent,v 1.3 2008/10/20 15:40:42 gauthierm Exp $ + $Id: global.ent,v 1.4 2008/11/07 18:38:17 cweiske Exp $ Contains global "macros" for all the XML documents. @@ -272,7 +272,6 @@ <!-- For links to the API documentation generated by phpdocumentor --> <!ENTITY phpdocbase.html-page2 "http://pear.php.net/package/HTML_Page2/docs/latest/HTML_Page2/HTML_Page2.html#method"> <!ENTITY phpdocbase.console-color "http://pear.php.net/package/Console_Color/docs/latest/Console_Color/Console_Color.html#method"> -<!ENTITY phpdocbase.console-commandline "http://pear.php.net/package/Console_CommandLine/docs/latest/Console_CommandLine/Console_CommandLine.html#method"> <!ENTITY phpdocbase.console-progressbar "http://pear.php.net/package/Console_ProgressBar/docs/latest/Console_ProgressBar/Console_ProgressBar.html#method"> <!ENTITY phpdocbase.datetime-date "http://pear.php.net/package/Date/docs/latest/Date/Date.html"> <!ENTITY phpdocbase.datetime-date.method "http://pear.php.net/package/Date/docs/latest/Date/Date.html#class_methods"> http://cvs.php.net/viewvc.cgi/peardoc/en/package/console/console-commandline/creating-the-parser.xml?r1=1.6&r2=1.7&diff_format=u Index: peardoc/en/package/console/console-commandline/creating-the-parser.xml diff -u peardoc/en/package/console/console-commandline/creating-the-parser.xml:1.6 peardoc/en/package/console/console-commandline/creating-the-parser.xml:1.7 --- peardoc/en/package/console/console-commandline/creating-the-parser.xml:1.6 Thu Oct 9 15:16:21 2008 +++ peardoc/en/package/console/console-commandline/creating-the-parser.xml Fri Nov 7 18:38:17 2008 @@ -1,5 +1,9 @@ <?xml version="1.0" encoding="utf-8"?> -<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.console.console-commandline.creating-the-parser"> +<refentry + xmlns="http://docbook.org/ns/docbook" + xmlns:phd="http://www.php.net/ns/phd" + version="lillet" xml:id="package.console.console-commandline.creating-the-parser" +> <refnamediv> <refname>Creating the parser</refname> <refpurpose> @@ -8,8 +12,8 @@ </refpurpose> </refnamediv> <refsection xml:id="package.console.console-commandline.creating-the-parser.intro"><info><title><classname>Console_CommandLine</classname> constructor</title></info> - - <para><classname>Console_CommandLine</classname> constructor takes an + + <para><classname>Console_CommandLine</classname> constructor takes an optional array of parameters explained in the table below. Note that if you are using an <acronym>XML</acronym> definition file, you can pass these parameters in it (see <acronym>XML</acronym> example for @@ -17,7 +21,7 @@ </para> <para> <table><title>Available parameters</title> - + <tgroup cols="4"> <thead> <row> @@ -38,13 +42,13 @@ <entry>description</entry> <entry>string</entry> <entry>no, but recommended for the help message</entry> - <entry>the description of your program: this should explain what + <entry>the description of your program: this should explain what your program is supposed to do</entry> </row> <row> <entry>version</entry> <entry>mixed (string or numeric)</entry> - <entry>no, note that if not given, the --version option will + <entry>no, note that if not given, the --version option will not be available</entry> <entry>the program version number</entry> </row> @@ -52,22 +56,22 @@ <entry>add_help_option</entry> <entry>boolean</entry> <entry>no, default to &true;</entry> - <entry>if set to &false; the parser will not generate + <entry>if set to &false; the parser will not generate automatically the <quote>help</quote> option</entry> </row> <row> <entry>add_version_option</entry> <entry>boolean</entry> <entry>no, default to &true;</entry> - <entry>if set to &false; the parser will not generate + <entry>if set to &false; the parser will not generate automatically the <quote>version</quote> option</entry> </row> <row> <entry>force_posix</entry> <entry>boolean</entry> <entry>no, default to &false;</entry> - <entry>if set to &true;, the parser will force - <acronym>POSIX</acronym> compliance (please see the gettext + <entry>if set to &true;, the parser will force + <acronym>POSIX</acronym> compliance (please see the gettext manual for more information)</entry> </row> </tbody> @@ -76,14 +80,14 @@ </para> </refsection> <refsection xml:id="package.console.console-commandline.creating-the-parser.php"><info><title>Using <acronym>PHP</acronym> code</title></info> - + <para>The examples below demonstrate how to instanciate <classname>Console_CommandLine</classname> and build a parser using <acronym>PHP</acronym> code. </para> <para> <example><info><title>The simplest way</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -99,7 +103,7 @@ </para> <para> <example><info><title>Alternative method</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -114,14 +118,14 @@ </para> </refsection> <refsection xml:id="package.console.console-commandline.creating-the-parser.xml"><info><title>Using an <acronym>XML</acronym> definition file</title></info> - + <para>The examples below demonstrate how to instanciate <classname>Console_CommandLine</classname> and build a parser using an - <acronym>XML</acronym> definition file, this can be very useful if you - have a big program or if you need to reuse your user interface settings + <acronym>XML</acronym> definition file, this can be very useful if you + have a big program or if you need to reuse your user interface settings for a web frontend for example. <example><info><title>The <acronym>XML</acronym> file</title></info> - + <programlisting role="xml"> <![CDATA[ <?xml version="1.0" encoding="utf-8" standalone="yes"?> @@ -135,7 +139,7 @@ </para> <para> <example><info><title>The <acronym>PHP</acronym> file</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -146,12 +150,15 @@ </programlisting> </example> </para> - <para> - Note: Using and <acronym>XML</acronym> string you would have called - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;fromXmlString"> - <function>fromXmlString()</function></link> instead of - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;fromXmlFile"> - <function>fromXmlFile()</function></link> of course. - </para> + + <note> + <para> + Using an <acronym>XML</acronym> string you would have called + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::fromXmlString">fromXmlString</phd:pearapi> + instead of + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::fromXmlFile">fromXmlFile</phd:pearapi> + of course. + </para> + </note> </refsection> </refentry> http://cvs.php.net/viewvc.cgi/peardoc/en/package/console/console-commandline/populating-the-parser.xml?r1=1.5&r2=1.6&diff_format=u Index: peardoc/en/package/console/console-commandline/populating-the-parser.xml diff -u peardoc/en/package/console/console-commandline/populating-the-parser.xml:1.5 peardoc/en/package/console/console-commandline/populating-the-parser.xml:1.6 --- peardoc/en/package/console/console-commandline/populating-the-parser.xml:1.5 Thu Oct 9 15:16:21 2008 +++ peardoc/en/package/console/console-commandline/populating-the-parser.xml Fri Nov 7 18:38:17 2008 @@ -1,5 +1,10 @@ <?xml version="1.0" encoding="utf-8"?> -<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.console.console-commandline.populating-the-parser"> +<refentry + xmlns="http://docbook.org/ns/docbook" + xmlns:phd="http://www.php.net/ns/phd" + version="lillet" + xml:id="package.console.console-commandline.populating-the-parser" +> <refnamediv> <refname>Populating the parser</refname> <refpurpose> @@ -7,9 +12,9 @@ </refpurpose> </refnamediv> <refsection xml:id="package.console.console-commandline.populating-the-parser.options"><info><title>Adding options</title></info> - + <refsection xml:id="package.console.console-commandline.populating-the-parser.options.background"><info><title>Some background</title></info> - + <para> Options are used to provide extra information to tune or customize the execution of a program. In case it wasn't clear, options are usually @@ -49,17 +54,17 @@ </para> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.options.adding"><info><title>Adding options with <classname>Console_CommandLine</classname></title></info> - + <para> To add options to your parser, just create the parser as explained in the - previous section and use the - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;addOption"> - <function>Console_CommandLine::addOption</function></link> method. + previous section and use the + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::addOption"/> + method. </para> <para> - The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;addOption"> - <function>Console_CommandLine::addOption</function></link> method takes - two arguments: + The + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::addOption"/> + method takes two arguments: <itemizedlist> <listitem> <simpara>the option name: a string that will be used to access the @@ -73,7 +78,7 @@ </listitem> </itemizedlist> <table><title>Available option parameters</title> - + <tgroup cols="5"> <thead> <row> @@ -132,7 +137,7 @@ <entry>string</entry> <entry>no, if not given it will default to the option name</entry> <entry>the name to display in the option help line</entry> - <entry>page_orientation (the help ligne will be: + <entry>page_orientation (the help ligne will be: --orientation=page_orientation)</entry> </row> </tbody> @@ -141,7 +146,7 @@ </para> <para> <example><info><title>Adding commandline options</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -151,7 +156,7 @@ 'version' => '0.0.1', // the version of your program )); -// Adding a simple option that takes no argument and that tell our program to +// Adding a simple option that takes no argument and that tell our program to // turn on verbose output: $parser->addOption( 'verbose', @@ -211,22 +216,22 @@ ( [verbose] => 1 [orientation] => rtl - [help] => - [version] => + [help] => + [version] => ) ]]> </programlisting> </para> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.options.actions"><info><title>Options actions</title></info> - + <para> Actions tell the parser how to handle option values, among other things they tell the parser if the option expects a value or not and how to store this value in the result object. </para> <refsection><info><title>StoreTrue</title></info> - + <para>This action tells the parser to store the value true in the result object if the option is present in the command line, for example: @@ -250,7 +255,7 @@ </para> </refsection> <refsection><info><title>StoreFalse</title></info> - + <para>This action tells the parser to store the value false in the result object if the option is present in the command line, for example:</para> @@ -273,14 +278,14 @@ </para> </refsection> <refsection><info><title>StoreString</title></info> - + <para>This action tells the parser that the option expects a value and to store this value as an integer in the result object, for example:</para> <para> <programlisting role="text">$ <yourprogram> -o out.txt</programlisting> </para> <para> - will store the string <quote>out.txt</quote> in + will store the string <quote>out.txt</quote> in <varname>$result->options['outfile']</varname>, assuming the option was defined like this: </para> @@ -296,7 +301,7 @@ </para> </refsection> <refsection><info><title>StoreInt</title></info> - + <para>This action tells the parser that the option expects a value and to store this value as an integer in the result object, for example:</para> <para> @@ -318,7 +323,7 @@ </para> </refsection> <refsection><info><title>StoreFloat</title></info> - + <para>This action tells the parser that the option expects a value and to store this value as a float in the result object, for example:</para> <para> @@ -340,9 +345,9 @@ </para> </refsection> <refsection><info><title>Counter</title></info> - + <para>This action tells the parser to increment the value in the result - object each time it encounters the option in the command line, for + object each time it encounters the option in the command line, for example:</para> <para> <programlisting role="text">$ <yourprogram> -vvvv</programlisting> @@ -372,22 +377,22 @@ </para> </refsection> <refsection><info><title>Help</title></info> - + <para>This action tells the parser to display the help message if it encounters the option in the command line, most of the time you won't need this since it is handled by Console_CommandLine internally.</para> </refsection> <refsection><info><title>Version</title></info> - + <para>This action tells the parser to display the program version if it encounters the option in the command line, as for Help action, chances - are that you won't need this since it is handled by + are that you won't need this since it is handled by Console_CommandLine internally.</para> </refsection> <refsection><info><title>Password</title></info> - + <para>This action allows the user to either type the password on the - commandline or to be prompted for it (will not echo on unix systems), + commandline or to be prompted for it (will not echo on unix systems), some examples:</para> <para> <programlisting role="php"> @@ -417,24 +422,24 @@ </para> </refsection> <refsection><info><title>Callback</title></info> - - <para>This action allows to specify a <acronym>PHP</acronym> callback - to handle user input. The callback must be a php callable and must + + <para>This action allows to specify a <acronym>PHP</acronym> callback + to handle user input. The callback must be a php callable and must accept five arguments:</para> <itemizedlist> <listitem> <simpara>the value of the option;</simpara> </listitem> <listitem> - <simpara>the + <simpara>the <classname>Console_CommandLine_Option_Callback</classname> instance</simpara> </listitem> <listitem> - <simpara>the + <simpara>the <classname>Console_CommandLine_Result</classname> instance</simpara> </listitem> <listitem> - <simpara>the + <simpara>the <classname>Console_CommandLine</classname> instance (the parser).</simpara> </listitem> <listitem> @@ -501,9 +506,9 @@ </refsection> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.arguments"><info><title>Adding arguments</title></info> - + <refsection xml:id="package.console.console-commandline.populating-the-parser.arguments.background"><info><title>Some background</title></info> - + <para> Arguments are for those pieces of information that your program absolutely, positively requires to run. @@ -525,18 +530,17 @@ </para> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.arguments.adding"><info><title>Adding arguments with <classname>Console_CommandLine</classname></title></info> - + <para> To add arguments to your parser, just create the parser as explained in - the previous section and use the - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;addArgument"> - <function>Console_CommandLine::addArgument</function></link> + the previous section and use the + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::addArgument"/> method. </para> <para> - The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&phpdocbase.console-commandline;addArgument"> - <function>Console_CommandLine::addArgument</function></link> - method takes two arguments: + The + <phd:pearapi phd:package="Console_CommandLine" phd:linkend="Console_CommandLine::addArgument"/> + method takes two arguments: <itemizedlist> <listitem> <simpara>the argument name: a string that will be used to access the @@ -545,14 +549,14 @@ <varname>$result->args['foo']</varname>;</simpara> </listitem> <listitem> - <simpara>the arguments parameters: an array of various informations + <simpara>the arguments parameters: an array of various informations as explained below.</simpara> </listitem> </itemizedlist> </para> <para> <table><title>Available arguments parameters</title> - + <tgroup cols="5"> <thead> <row> @@ -591,7 +595,7 @@ </para> <para> <example><info><title>Adding commandline arguments</title></info> - + <programlisting role="php"> <![CDATA[ <?php @@ -643,16 +647,16 @@ </refsection> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.subcommands"><info><title>Adding sub-commands</title></info> - + <refsection xml:id="package.console.console-commandline.populating-the-parser.subcommands.background"><info><title>What are sub-commands ?</title></info> - + <para> Some programs are very complex, you can't do anything about that but you need to provide the best user interface possible in order to have happy users. In some cases, sub-commands can be very useful, take the PEAR installer for example, it is much more clearer to separate the installer functionalities than to mix all functionalities in the same - interface, that's why you have an interface like: + interface, that's why you have an interface like: </para> <programlisting role="text"> <![CDATA[ @@ -663,7 +667,7 @@ </programlisting> </refsection> <refsection xml:id="package.console.console-commandline.populating-the-parser.subcommands.adding"><info><title>Adding sub-commands with <classname>Console_CommandLine</classname></title></info> - + <para>TODO: develop this section</para> </refsection> </refsection>