svn: /pear/peardoc/trunk/en/package/php/php-codesniffer/ advanced-usage.xml config-options.xml reporting.xml usage.xml

squiz                                    Mon, 30 Aug 2010 01:10:11 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=302876

Log:
Added information about the new --encoding command line arg and fixed docs to show that reports are no longer written to screen when using the --report-file option.

Changed paths:
    U   pear/peardoc/trunk/en/package/php/php-codesniffer/advanced-usage.xml
    U   pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml
    U   pear/peardoc/trunk/en/package/php/php-codesniffer/reporting.xml
    U   pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/advanced-usage.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/advanced-usage.xml	2010-08-30 00:42:43 UTC (rev 302875)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/advanced-usage.xml	2010-08-30 01:10:11 UTC (rev 302876)
@@ -173,6 +173,25 @@
  </refsection>


+ <refsection xml:id="package.php.php-codesniffer.advanced-usage.encoding"><info><title>Specifying an Encoding</title></info>
+  <para>
+   Some PHP_CodeSniffer reports output UTF-8 encoded XML, which can cause problems if your files are already UTF-8 encoded. In this case, some content from your files (generally comments) are used within error messages and may be double-encoded. To help PHP_CodeSniffer encode reports correctly, you can specify the encoding of your source files using the <literal>--encoding</literal> command line argument.
+  </para>
+  <example><info><title>Specifying UTF-8 encoding</title></info>
+   <screen>
+<![CDATA[
+$ phpcs --encoding=utf-8 /path/to/code
+]]>
+   </screen>
+  </example>
+  <note>
+   <simpara>
+    The default encoding used by PHP_CodeSniffer is ISO-8859-1.
+   </simpara>
+  </note>
+ </refsection>
+
+
  <refsection xml:id="package.php.php-codesniffer.advanced-usage.config-set"><info><title>Setting Configuration Options</title></info>
   <para>
    PHP_CodeSniffer has some configuration options that can be set. Individual coding standards may also require configuration options to be set before functionality can be used. <link linkend="package.php.php-codesniffer.config-options">View a full list of configuration options.</link>

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml	2010-08-30 00:42:43 UTC (rev 302875)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/config-options.xml	2010-08-30 01:10:11 UTC (rev 302876)
@@ -106,6 +106,22 @@
   </refsection>


+  <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.encoding"><info><title>Setting the Default Encoding</title></info>
+   <para>
+    By default, PHP_CodeSniffer will treat all source files as if they use ISO-8859-1 encoding. This can cause double-encoding problems when generating UTF-8 encoded XML reports. To help PHP_CodeSniffer encode reports correctly, you can specify the encoding of your source files using the <literal>--encoding</literal> command line argument, but you can also change the default encoding by setting the <literal>encoding</literal> configuration option.
+   </para>
+   <example><info><title>Setting the default encoding to UTF-8</title></info>
+    <screen>
+     <userinput>
+<![CDATA[
+$ phpcs --config-set encoding utf-8
+]]>
+     </userinput>
+    </screen>
+   </example>
+  </refsection>
+
+
   <refsection xml:id="package.php.php-codesniffer.config-options.php-codesniffer.tab-width"><info><title>Setting the Default Tab Width</title></info>
    <para>
     By default, PHP_CodeSniffer will not convert tabs to spaces in checked files. Specifying a tab width will make PHP_CodeSniffer replace tabs with spaces. You can force PHP_CodeSniffer to replace tabs with spaces by default by setting the <literal>tab_width</literal> configuration option.

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/reporting.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/reporting.xml	2010-08-30 00:42:43 UTC (rev 302875)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/reporting.xml	2010-08-30 01:10:11 UTC (rev 302876)
@@ -376,7 +376,7 @@
    PHP_CodeSniffer always prints the specified report to the screen, but it can also be told to write a copy of the report to a file. When writing to a file, all internal parsing errors and verbose output PHP_CodeSniffer produces will not be included in the file. This feature is particularly useful when using report types such as XML and CSV that are often parsed by scripts or used with continuous integration software.
   </para>
   <para>
-   To write a copy of a report to a file, use the <literal>--report-file</literal> command line argument. Note that a copy of the report will also be written to the screen.
+   To write a copy of a report to a file, use the <literal>--report-file</literal> command line argument.
   </para>
   <example><info><title>Writing a report to a file</title></info>
    <screen>
@@ -385,6 +385,11 @@
 ]]>
    </screen>
   </example>
+  <note>
+   <simpara>
+    The report will not be written to the screen when using this option. If you still want to view the report, use the <literal>-v</literal> command line argument to print verbose output.
+   </simpara>
+  </note>
  </refsection>

 </refentry>

Modified: pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml
===================================================================
--- pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml	2010-08-30 00:42:43 UTC (rev 302875)
+++ pear/peardoc/trunk/en/package/php/php-codesniffer/usage.xml	2010-08-30 01:10:11 UTC (rev 302876)
@@ -16,7 +16,7 @@
     [--report=<report>] [--report-width=<reportWidth>] [--report-file=<reportfile>]
     [--severity=<severity>] [--error-severity=<severity>] [--warning-severity=<severity>]
     [--config-set key value] [--config-delete key] [--config-show]
-    [--standard=<standard>] [--sniffs=<sniffs>]
+    [--standard=<standard>] [--sniffs=<sniffs>] [--encoding=<encoding>]
     [--generator=<generator>] [--tab-width=<tabWidth>] <file> ...
         -n            Do not print warnings (shortcut for --warning-severity=0)
         -w            Print both warnings and errors (on by default)
@@ -32,6 +32,7 @@
                       (only valid if checking a directory)
         <patterns>    A comma separated list of patterns that are used
                       to ignore directories and files
+        <encoding>    The encoding of the files being checked (default is iso-8859-1)
         <sniffs>      A comma separated list of sniff codes to limit the check to
                       (all sniffs must be part of the specified standard)
         <severity>    The minimum severity that an error or warning must have
@@ -46,7 +47,6 @@
                       (the "full" report is printed by default)
         <reportWidth> How many columns wide screen reports should be printed
         <reportfile>  Write the report to the specified file path
-                      (report is also written to screen)
 ]]>
    </screen>
   </para>