Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Update of the introductory sections of the manual

  • Loading branch information...
commit c729405f0ceb1427f7a5dbe23a1b701aea211175 1 parent f20baa4
@johan162 authored
View
21 docs/docbook5/en/source/chapters/gettingstarted.xml
@@ -432,14 +432,17 @@
become a bit tedious and the large (and growing) amount of built-in tasks and filters
can sometimes make it difficult to remember the exact syntax of all the available
features.</para>
- <para>To help with this the Phing distribution contains a Relax NG Grammar (REgular LAnguage
- for XML Next Generation, <link xlink:href="http://www.relaxng.org/"
+ <para>To help with this the Phing distribution contains a Relax NG Grammar (<emphasis
+ role="bold">RE</emphasis>gular <emphasis role="bold">LA</emphasis>nguage for
+ <emphasis role="bold">X</emphasis>ML <emphasis role="bold">N</emphasis>ext <emphasis
+ role="bold">G</emphasis>eneration, <link xlink:href="http://www.relaxng.org/"
>http://www.relaxng.org/</link>) file that describes the (formal) syntax of the
- build files. This grammar can help validate and write Phing build files since there are
- many XML editors which can make use of this type of grammar to validate, on the fly, as
- well as do context-sensitive auto-completion. Especially the auto-complete feature can
- significantly reduce the time it takes to write a correct, and possible complex, Phing
- build files.</para>
+ build files. This grammar can be used to validate build files. However, the most
+ beneficial use of the grammar is together with a schema aware XML editor. Such an editor
+ can make auto-completion based on the grammar. This feature makes writing complex build
+ files significantly easier since it is usually enough to enter the first letter of an
+ element to have the rest of the element written automatically as well as any compulsory
+ attributes.</para>
<para>Most XML editors can be told to what schema (or model) to use for validation and
auto-completion by adding a specification in the beginning of the XML file. For example,
the following two lines in the beginning of an XML file would do (of course the exact
@@ -452,8 +455,8 @@
Please note that since the phing-grammar does not have an official designation we must
use the absolute filename to specify the grammar (instead of a canonical URI that is
resolved by the systems XML-catalogue).</para>
- <para>This grammar is available (as a plain text file) in the distribution at: <filename>
- /etc/phing-grammar.rng </filename>
+ <para>This grammar is available (as a plain text file) in the distribution at:
+ <filename>/etc/phing-grammar.rng</filename>
</para>
<para>Since we do not want to neither endorse nor forget any particular XML editor with this
capability we do not make available such a list of editors. Instead, spending a few
View
67 docs/docbook5/en/source/chapters/introduction.xml
@@ -55,11 +55,10 @@
Andreas Aderhold, who was responsible for <acronym>Phing</acronym>/r1, designed and
wrote much of the Phing/r2 that followed. Phing/r2 became the Phing-1.0 that exists
today for PHP4.</para>
- <para>The current development of <acronym>Phing</acronym> is focused on <acronym>Phing
- 2</acronym>, which has involved a number of bugfixes, functionality enhancements,
- and most significantly a conversion of the codebase to use new <acronym>PHP5</acronym>
- features such as abstract classes, interfaces, and try/catch/throw exception
- handling.</para>
+ <para>The current development version of <acronym>Phing 2.x</acronym>, requires
+ <acronym>PHP5</acronym> (at least 5.2.x) and makes use of many of the available
+ features in PHP5.2 to achieve a high degree of modularization, code efficiency as well
+ as stability and testability.</para>
</sect1>
<sect1>
<title>How Phing Works</title>
@@ -88,7 +87,65 @@
>http://phing.tigris.org</link> and subscribe to the <literal>dev</literal>
mailing list</para>
</listitem>
+ <listitem>
+ <para>Report bugs you find on the Phing Trac system available at <link
+ xlink:href="http://www.phing.info/trac/"
+ >http://www.phing.info/trac/</link></para>
+ </listitem>
+ <listitem>
+ <para>.. or start to actively participate in the development (see below) </para>
+ </listitem>
</itemizedlist>
+ <sect2>
+ <title> Participating in the development </title>
+
+ <para>As of 1 january 2012 all Phing evelopment is based on Git and the project is hosted at
+ GitHub (<link xlink:href="https://github.com/">https://github.com/</link>)</para>
+ <para>In order to participate in the development you will need to follow these basic
+ steps</para>
+ <orderedlist>
+ <listitem>
+ <para>Register a free account at GitHub</para>
+ </listitem>
+ <listitem>
+ <para>Clone the official Phing repository
+ (<literal>phingofficial/phing</literal>)</para>
+ </listitem>
+ <listitem>
+ <para>Read up on the documentation at GitHub on how to ask the official Phing
+ maintainers to accept some of your changes by creating pull request.</para>
+ </listitem>
+ </orderedlist>
+ <para>To have a change set accepted it should have these components</para>
+ <itemizedlist>
+ <listitem>
+ <para>Follow the naming and coding principle used by Phing</para>
+ </listitem>
+ <listitem>
+ <para>Make sure you have added documentation for your addition(s) (including
+ examples)</para>
+ </listitem>
+ <listitem>
+ <para>Make sure you have added unitest code which exercises any new task you
+ have added</para>
+ </listitem>
+ <listitem>
+ <para>Be polite!</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <note>
+ <para>If you have not worked with Git before and are coming from subversion
+ there is a bit of re-adjustment needed. Fortunately there are several
+ <emphasis>SVN-To-Git</emphasis> re-learning guides available (for
+ example <link xlink:href="http://git.or.cz/course/svn.html"
+ >http://git.or.cz/course/svn.html</link>. </para>
+ <para>However, it is probably best to forget about Subversion and realize that
+ Git is a different animal so trying to think of everything in terms of
+ Subversion is not really helpful in the long run. </para>
+ </note>
+ </para>
+ </sect2>
</sect1>
</chapter>
View
98 docs/docbook5/en/source/chapters/settingup.xml
@@ -17,16 +17,16 @@
<literal>--with-libxml2</literal>, as well as <literal>--with-xsl</literal> if you
want to make use of advanced functionality.</para>
- <para> For more information on PHP and the required modules see the PHP <link
+ <para>For more information on PHP and the required modules see the PHP <link
xlink:href="Bibliography.html#php">[php]</link> website. For a brief list of
software dependencies see below.</para>
<sect2>
<title> Operating Systems </title>
- <para>Designed for portability from the get go, Phing runs on all platforms that run
- PHP. However some advanced functionality may not work properly or is simply ignored
- on some platforms (i.e. chmod on the Windows platform).</para>
+ <para>Designed for portability from the get go, Phing runs on all platforms that run PHP. However
+ some advanced functionality may not work properly or is simply ignored on some
+ platforms (i.e. <literal>chmod</literal> on the Windows platform).</para>
<para>To get the most out of Phing, a Unix style platform is recommended. Namely: Linux,
FreeBSD, OpenBSD, etc.</para>
@@ -34,7 +34,7 @@
<sect2>
<title> Software Dependencies </title>
- <para>For a detailed list of required / optional software and libraries, refer to the
+ <para>For a detailed list of required and/or optional software and libraries, refer to the
following table of Software Dependencies.</para>
<para>NB: This list is not exhaustive, please refer to individual Phing tasks to find
@@ -168,7 +168,7 @@
</table>
<warning>
- <para>Phing does not work with safe mode enabled!</para>
+ <para>Phing does not work with safe mode enabled in PHP!</para>
</warning>
</sect2>
</sect1>
@@ -184,12 +184,11 @@
<para>There are several ways to get a Phing distribution package. If you do not want to
participate in developing Phing itself it is recommended that you get the latest
snapshot or stable packaged distribution. If you are interested in helping with
- Phing development, get a <acronym>git</acronym> revision of the files, as described
- below.</para>
+ Phing development, register an account at GitHub as described below.</para>
- <para> The easiest way to obtain the distribution package is to visit the Phing website
- <link xlink:href="Bibliography.html#phing">[phing] </link>and download the
- current distribution package in the format you desire.</para>
+ <para>The easiest way to obtain the distribution package is to visit the Phing website <link
+ xlink:href="Bibliography.html#phing">[phing] </link>and download the current
+ distribution package in the format you desire.</para>
<para>As of version 2.0, you have the option of downloading a PEAR-installable package
or the full phing distribution. If you wish to modify phing we suggestion
downloading the full version so that you can (e.g.) create your own PEAR package. If
@@ -197,31 +196,20 @@
package, download &amp; install the PEAR package.</para>
</sect2>
<sect2>
- <title> Getting A Development Copy From Subversion </title>
-
- <para>You are encouraged to contibute to the development of Phing. If you want to
- participate or if you are simply interested in the latest features and development,
- obtain a Subversion copy as described in the following paragraphs.</para>
-
- <para> The SVN revisions of Phing are not bullet-proof and may fail to execute properly
- on your machine. Only obtain the development versions if you are absolutely aware of
- limitations and constraints of such an action. Additionally you should sign up to
- the development mailinglist to report and notice errors and incompatibilities.</para>
-
- <para> We assume that you are running a Unix style operating system. So we expect the
- Subversion software is installed and the <command>svn</command> executable is in
- your system's search path. However, the steps for a Windows based system are very
- similar. There is plenty additional information available on how to use Subversion
- <link xlink:href="Bibliography.html#cvs-howto">[svn-howto]</link>.</para>
-
- <para>To check out the project source repository type:</para>
-
- <screen>$&gt; svn checkout http://svn.phing.info/trunk</screen>
-
- <para> You can also browse the entire Phing source (including previous versions and
- development branches) on <link xlink:href="http://www.phing.info/trac/browser"
- role="external">http://www.phing.info/trac/browser</link>.</para>
+ <title>Getting the latest source from Phing Git repository</title>
+ <para>The latest snapshot can always be downloaded directly the official Phing Git
+ repository. However, be warned that there is not guarantee that the momentous state
+ of the repository represents a completely stable application without any
+ problems.</para>
+ <para>You can download a snapshot as a zip-tarball from:</para>
+ <itemizedlist>
+ <listitem>
+ <para><link xlink:href="https://github.com/phingofficial/phing"
+ >https://github.com/phingofficial/phing</link></para>
+ </listitem>
+ </itemizedlist>
</sect2>
+
</sect1>
<sect1>
<title> PEAR Install </title>
@@ -231,8 +219,7 @@
<screen>$&gt; pear channel-discover pear.phing.info
$&gt; pear install phing/phing</screen>
<para>The pear installer will check any dependencies and place the phing script (phing or
- phing.bat) into your PHP script directoy (i.e. where the &quot;pear&quot; script
- resides).</para>
+ phing.bat) into your PHP script directoy (i.e. where the "pear" script resides).</para>
</sect1>
<sect1>
<title> Non-PEAR Install </title>
@@ -294,7 +281,7 @@ $&gt; pear install phing/phing</screen>
</itemizedlist>
<para>If you are using Phing in conjunction with another application, you may need to add
- additional paths to PHP_CLASSPATH.</para>
+ additional paths to <literal>PHP_CLASSPATH</literal>.</para>
<sect2>
<title> Unix </title>
@@ -326,16 +313,16 @@ set PATH=%PATH%;%PHING_HOME%\bin</screen>
least the following:</para>
<itemizedlist>
<listitem>
- <para>If you want Phing to be able to use other packages / classes, you can
- either add them to the PHP_CLASSPATH or to PHP's include_path.</para>
+ <para>If you want Phing to be able to use other packages / classes, you can either add them to
+ the <literal>PHP_CLASSPATH</literal> or to PHP's include_path.</para>
</listitem>
<listitem>
- <para>Some Tasks in phing/tasks/ext may require 3rd party libraries to be
- installed. Generally, tools with compatible license (and stable releases)
- are included in phing/lib so that outside dependencies can be avoided. PEAR
- libs will not, however, be bundled with Phing since they are generally
- bundled with PHP. If you are using a 3rd party task, see the Task
- documentation to be aware of any dependencies.</para>
+ <para>Some Tasks in <filename role="dir">phing/tasks/ext</filename> may require 3rd party
+ libraries to be installed. Generally, tools with compatible license (and
+ stable releases) are included in phing/lib so that outside dependencies can
+ be avoided. PEAR libs will not, however, be bundled with Phing since they
+ are generally bundled with PHP. If you are using a 3rd party task, see the
+ Task documentation to be aware of any dependencies.</para>
</listitem>
</itemizedlist>
@@ -367,6 +354,25 @@ set PATH=%PATH%;%PHING_HOME%\bin</screen>
<literal>ftp.upload</literal> set to true.</para>
<screen>$ phing -Dftp.upload=true</screen>
</sect2>
+ <sect2>
+ <title>Supported command line arguments</title>
+ <para>As of version 2.4.9 the following command line arguments are supported</para>
+ <programlisting> -h -help print this message
+ -l -list list available targets in this project
+ -v -version print the version information and exit
+ -q -quiet be extra quiet
+ -verbose be extra verbose
+ -debug print debugging information
+ -longtargets show target descriptions during build
+ -logfile &lt;file> use given file for log
+ -logger &lt;classname> the class which is to perform logging
+ -f -buildfile &lt;file> use given buildfile
+ -D&lt;property>=&lt;value> use value for given property
+ -propertyfile &lt;file> load all properties from file
+ -find &lt;file> search for buildfile towards the root of the
+ filesystem and use it
+ -inputhandler &lt;file> the class to use to handle user input</programlisting>
+ </sect2>
</sect1>
</chapter>
Please sign in to comment.
Something went wrong with that request. Please try again.