<?xml version="1.0" encoding="iso-8859-1"?>

<chapter id="chapter-scripts">
 <title>Automatization with scripts</title>

 <para>
  The PHP manual is very big and the PHP sources change every day. To help the
  documentation writers's work, we have developed a couple of scripts during
  the last years. Below you will find a list of the scripts, as well a short
  explanation and usage tips for each one.
 </para>

 <sect1 id="scripts.aspell.php">
  <title>aspell.php</title>
  <para>
   This script can be used to escape or unescape manual files for use with
   <command>aspell</command>. Escaping moves the contents of tags with
   non-English texts (like <literal>&lt;type&gt;</literal>,
   <literal>&lt;parameter&gt;</literal> or <literal>&lt;function&gt;</literal>)
   to the attribute <literal>aspell</literal> so the Aspell will ignore them.
   Unescaping is the opposite process.
  </para>
  <para>
   File <filename>en.pws</filename> contains words not included in the Aspell
   dictionary but valid in the PHP manual and can be used as the personal
   dictionary.
  </para>
 </sect1>
 
 <sect1 id="scripts.check-references.php">
  <title>check-references.php</title>
  <para>
   This script tries to parse the PHP sources and compares the facts about
   function parameters (their count, types, optionality and the need of
   passing them as reference) with the documentation. Only easy parsable
   functions from Zend, extensions, PECL and SAPI sources are checked.
  </para>
  <para>
   Used rules are not absolutely precise, they are rather heuristics. Thus not
   everything printed automatically denotes errors and sources should be
   always read by a human before modifying the documentation. If the sources
   correspond to the documentation and this script still produces error,
   function should be added to one of <varname>$difficult_*</varname> arrays
   defined in the beginning of this script.
  </para>
 </sect1>
 
 <sect1 id="scripts.diff-en-rev.php">
  <title>diff_en_rev.php</title>
  <para>
   One of the scripts helping translators.
  </para>
  <para>
   It prints a diff between the current English version and the translated
   version of a file. It uses the <literal>&lt;!-- EN-Revision
   --&gt;</literal> tag to determine the translated version. If the local
   English file has different revision, <command>cvs diff</command> is
   executed to obtain the list of changes.
  </para>
  <para>
   It is possible to pass a directory name instead of file name. In this case,
   list of modified files in the directory is printed.
  </para>
 </sect1>
 
 <sect1 id="scripts.extensions.xml.php">
  <title>extensions.xml.php</title>
  <para>
   The <filename>extensions.xml.php</filename> script creates the <ulink
    url="&url.extension.cat;">extension categorization appendix</ulink>. It
   collects the data from the reference.xml files and updates the
   <filename>en/appendices/extensions.xml</filename> file.
  </para>
  <para>
   The tags supported for the <filename>reference/*/reference.xml</filename>
   files include:
   <table>
    <title/>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Tag</entry>
       <entry>Explanation</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>&lt;!-- Purpose: xx --&gt;</entry>
       <entry>
        <para>
         The purpose of the extension, specified by an ID. There are several
         IDs available, which can be consulted in the
         <filename>en/extensions.ent</filename> file. They look like
         <literal>database.vendors</literal> or <literal>xml</literal>.
        </para>
        <para>
         If none of the available categories fits your extension, you can
         create a new one. To do so, you must add a new entity in the
         <filename>en/extensions.ent</filename> file, like:
         <literal>&lt;!ENTITY extcat.purpose.xml '&lt;title&gt;XML
          Manipulation&lt;/title&gt;'&gt;</literal>. After this, you still
         need to edit <filename>en/appendices/extensions.xml</filename> and
         create a new section for your ID, by copying an already existent
         section. This isn't done automatically to allow you to choose the
         order of the sections.
        </para>
       </entry>
      </row>
      <row>
       <entry>&lt;!-- Membership: xx, yy --&gt;</entry>
       <entry>
        This tag can have multiple values, that should be separated by commas.
        Valid values include: <literal>core</literal> (for PHP core
        extensions, like the strings or date extension),
        <literal>pecl</literal> (if the extension lives in PECL),
        <literal>bundled</literal> (if the extension is bundled with the main
        PHP distribution), and <literal>external</literal> (if the extension
        relies on external - and not bundled - libraries).
       </entry>
      </row>
      <row>
       <entry>&lt;!-- State: xx --&gt;</entry>
       <entry>
        This tag is optional and can only have two values, either
        <literal>deprecated</literal> or <literal>experimental</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <note>
   <para>
    If you mark an extension as deprecated and if it is very old and unusable,
    you shouldn't add the purpose and membership tags, so that the extension
    doesn't appear in the appendix (to avoid confusing users).
   </para>
  </note>
  <para>
   The script should warn you for missing tags or even bogus values, although
   it won't report any XML errors. So, you have the responsability to run
   <command>make test</command> before running this script. Failing to do so,
   may lead to unexpected results.
  </para>
  <note>
   <para>
    This script requires PHP &gt;= 5 with SimpleXML.
   </para>
  </note>
 </sect1>

 <sect1 id="scripts.html-syntax.php">
  <title>html_syntax.php</title>
  <para>
   This script is used in the build process to syntax highlight PHP examples
   both for the online and downloadable manuals.
  </para>
 </sect1>

 <sect1 id="scripts.iniupdate">
  <title>iniupdate/*.php</title>
  <para>
   The <filename>iniupdate</filename> directory contains a set of scripts that
   are used to generate the <filename>en/appendices/ini.xml</filename> table.
   They also update the information that is dispersed in the
   <filename>en/reference/*/ini.xml</filename> files.
  </para>
  <para>
   To use this script, you must download all the PHP 4, 5 and 6 sources (which
   will take a long time), so that the script can create a DB with the history
   of the changes between the versions. To do that, you can just run the
   <command>./update-all</command> script. If you are using the 'functable'
   script as well, you may just create a symlink to its sources, as the
   sources are the same :) The rest of the process is explained in the README
   file.
  </para>
  <para>
   The core of the scripts is in <filename>ini_search_lib.php</filename>, and
   it is very regex based. The main regexes work correctly, although some
   heuristics are used to catch the <function>cfg_get_*</function> uses. The
   <filename>generate_changelog.php</filename> is used to generate the
   changelog (based on the data previously collected in the DB).
  </para>
  <note>
   <para>
    This script requires PHP &gt;= 5 with SQLite.
   </para>
  </note>
 </sect1>

 <sect1 id="scripts.xml-check.php">
  <title>xml-check.php</title>
  <para>
   Build process of the whole manual can be very slow. This script takes one
   XML file, creates <filename>xml-check.xml</filename> in the documentation
   root with the beginning and ending DocBook tags and parses this file with
   <command>xmllint</command>. Beginning tags are taken from
   <filename>manual.xml.in</filename>.
  </para>
  <para>
   Detected errors are printed thus empty output means correct file.
  </para>
 </sect1>
 
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"howto.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->