首页 » 教程文章 » 文章查看
|
PHP手册翻译/编译指南[2]
作者:Haohappy
来源:PHPEye开源社区 2007-04-14
收藏:
Below are some "skeletons" to copy and paste from when adding documentation. All of these files should end with a line ending ("\n"). If a section does not exist (like a ChangeLog), simply don't include that refsect1 inside the documentation.
Note: The documentation skeletons below are new, from around August of 2004.
Example 8-1. A function skeleton (func-name.xml)
<?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.61 $ --> <refentry id="function.func-name"> <refnamediv> <refname>func_name</refname> <refpurpose>The func_name purpose</refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; <methodsynopsis> <!-- Example: All functions have this --> <type>thereturned type</type><methodname>func_name</methodname> <!-- Example: Required parameter --> <methodparam><type>int</type><parameter>firstparameter</parameter></methodparam> <!-- Example: Optional parameter --> <methodparam choice="opt"><type>string</type><parameter>secondparameter</parameter></methodparam> <!-- Example: Passed by reference --> <methodparam><type>bool</type><parameter role="reference">thirdparameter</parameter></methodparam> <!-- Example: If no methodparams exist (void), use this --> <void /> </methodsynopsis> <para> The functions description goes here. </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; <para> <variablelist> <varlistentry> <term><parameter>firstparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> <varlistentry> <term><parameter>secondparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> <varlistentry> <term><parameter>thirdparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> </variablelist> </para> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> What this function returns, first on success, then failure. If simply true on success and false on failure, just use &return.success; here. </para> </refsect1> <refsect1 role="changelog"> &reftitle.changelog; <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>&Version;</entry> <entry>&Description;</entry> </row> </thead> <tbody> <row> <entry>Write the PHP version here (Ex. 4.3.0)</entry> <entry> Describe the change </entry> </row> <row> <entry>...</entry> <entry> ... </entry> </row> </tbody> </tgroup> </informaltable> </para> </refsect1> <refsect1 role="examples"> &reftitle.examples; <para> <example> <title><function>functionname</function> example</title> <programlisting role="php"> <![CDATA[ <?php if ($anexample === true) { echo 'Use the PEAR Coding standards'; } if ($thereisoutput === 'and it is multiple lines') { echo 'Use a screen like we did below'; } ?> ]]> </programlisting> &example.outputs.similar; <screen> <![CDATA[ Use the PEAR Coding standards Use a screen like we did below ]]> </screen> </example> </para> </refsect1> <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> <member><function>somefunc</function></member> <member><function>another_func</function></member> <member>The <link linkend="something">something appendix</link></member> </simplelist> </para> </refsect1> </refentry>
<!-- 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:"../../../../manual.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 -->
|
|
Example 8-2. A reference.xml skeleton
<?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.61 $ --> <!-- Purpose: xx --> <!-- Membership: xx --> <!-- State: xx --> <reference id="ref.extname"> <title>Extname &Functions;</title> <titleabbrev>Extname</titleabbrev>
<partintro> <section id="extname.intro"> &reftitle.intro; <para> </para> </section>
<section id="extname.requirements"> &reftitle.required; <para> </para> </section>
&reference.extname.configure; &reference.extname.ini;
<section id="extname.resources"> &reftitle.resources; &no.resource; </section>
&reference.extname.constants; </partintro>
&reference.extname.functions;
</reference>
<!-- 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:"../../../manual.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 -->
|
|
There are several PECL related entities inside of language-snippets.ent. Be sure to include information on where Windows users can find the DLL.
Example 8-3. A configure.xml skeleton
<?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.61 $ --> <section id="extname.installation"> &reftitle.install; <para> To enable extname support, configure PHP with <option role="configure">theconfigoption</option> </para> <para> Windows users ... </para> </section>
<!-- 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:"../../../manual.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 -->
|
|
Example 8-4. A constants.xml skeleton
<?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.61 $ --> <section id="extname.constants"> &reftitle.constants; &extension.constants; <para> <variablelist> <varlistentry> <term> <constant>CONSTANT_NAME</constant> (<type>itstype</type>) </term> <listitem> <simpara> </simpara> </listitem> </varlistentry> </variablelist> </para> </section>
<!-- 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:"../../../manual.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 -->
|
|
Example 8-5. A ini.xml skeleton
<?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.61 $ --> <section id="extname.configuration"> &reftitle.runtime; &extension.runtime; <para> <table> <title>Extname &ConfigureOptions;</title> <tgroup cols="3"> <thead> <row> <entry>&Name;</entry> <entry>&Default;</entry> <entry>&Changeable;</entry> <entry>Changelog</entry> </row> </thead> <tbody> <row> <entry>theini_option</entry> <entry>itsvalue</entry> <entry>its PHP_INI_* value</entry> <entry>leave this blank. it will be filled automatically</entry> </row> </tbody> </tgroup> </table>
&php_ini_constants; </para> &ini.descriptions.title; <para> <variablelist> <varlistentry id="ini.extname.theini-option"> <term> <parameter>theini_option</parameter> <type>thetype</type> </term> <listitem> <para> </para> </listitem> </varlistentry> </variablelist> </para> </section>
<!-- 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:"../../../manual.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 -->
收藏:
|
|
评论 (关闭)
|