goba Sun Nov 18 08:05:35 2001 EDT
Modified files:
/phpdoc/howto generating.xml howto.ent howto.html.tar.gz howto.xml
working.xml
Log:
Adding some more translator advice, a new section about online
generation of docs, tips on mailing list filtering, conventions
corrected, added text about function naming...
Index: phpdoc/howto/generating.xml
diff -u phpdoc/howto/generating.xml:1.4 phpdoc/howto/generating.xml:1.5
--- phpdoc/howto/generating.xml:1.4 Sun Nov 11 04:54:38 2001
+++ phpdoc/howto/generating.xml Sun Nov 18 08:05:34 2001
@@ -271,6 +271,43 @@
</note>
</chapter>
+ <chapter id="chapter-online-generation">
+ <title>The Online Generation System</title>
+
+ <para>
+ The online generation system is working
+ at <ulink url="&url.php.rsync;">&url.php.rsync;</ulink>.
+ </para>
+ <para>
+ This system generates manuals for all languages
+ with a <filename>language-defs.ent</filename> file
+ in the translation directory. However the listing of
+ languages at <ulink url="&url.php.docs;">&url.php.docs;</ulink>
+ and <ulink url="&url.php.docdownload;">&url.php.docdownload;</ulink>
+ are static, so only manually added languages show up in
+ those listings.
+ </para>
+ <para>
+ This generator system only builds a new online manual,
+ and new downloadable files from one language, if
+ it is modified in a one day period. The build process
+ takes hours for only one language, so not all languages
+ can be built in one day. During the generation, a
+ <filename>build.log</filename> is saved with build
+ information. See the <link linkend="translation-practical">section
+ for translators</link> about the <filename>build.log</filename>
+ file. If there were some errors in the build process,
+ you can find the errors loged in this file.
+ </para>
+ <para>
+ The automatic build process updates the online manual,
+ and all downloadable ones, excluding the CHM versions.
+ The CHM version is built manually, because it requires
+ a Microsoft Windows system to work, and therefore it
+ is not too easy to automate.
+ </para>
+ </chapter>
+
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.9 phpdoc/howto/howto.ent:1.10
--- phpdoc/howto/howto.ent:1.9 Mon Oct 22 08:00:26 2001
+++ phpdoc/howto/howto.ent Sun Nov 18 08:05:34 2001
@@ -9,11 +9,13 @@
<!ENTITY email.jirka "[EMAIL PROTECTED]">
<!ENTITY email.jeroen "[EMAIL PROTECTED]">
<!ENTITY email.phpdoc "[EMAIL PROTECTED]">
+<!ENTITY email.phpdev "[EMAIL PROTECTED]">
<!ENTITY email.group.php "[EMAIL PROTECTED]">
<!-- General PHP.net links -->
<!ENTITY url.php "http://www.php.net/";>
-<!ENTITY url.php.cvs "http://cvs.php.net";>
+<!ENTITY url.php.rsync "http://rsync.php.net/";>
+<!ENTITY url.php.cvs "http://cvs.php.net/";>
<!ENTITY url.php.cvsaccount "http://www.php.net/cvs-php.php";>
<!ENTITY url.php.anoncvs "http://www.php.net/anoncvs.php";>
<!ENTITY url.php.docs "http://www.php.net/docs.php";>
@@ -70,7 +72,7 @@
<!ENTITY url.support "http://www.php.net/support.php";>
<!ENTITY url.status "http://toye.php.net/~rasmus/status.php";>
<!ENTITY url.status.hu "http://toye.php.net/~rasmus/status.php?l=hu";>
-
+<!ENTITY url.revcheck.it "http://www.php.net/manual/it/revcheck.html";>
<!-- For Misc section -->
<!ENTITY url.zend.phpfunc "http://www.zend.com/phpfunc/";>
Index: phpdoc/howto/howto.html.tar.gz
Index: phpdoc/howto/howto.xml
diff -u phpdoc/howto/howto.xml:1.15 phpdoc/howto/howto.xml:1.16
--- phpdoc/howto/howto.xml:1.15 Mon Oct 22 08:00:26 2001
+++ phpdoc/howto/howto.xml Sun Nov 18 08:05:34 2001
@@ -23,7 +23,6 @@
Sections need to be added:
How to add a new section/funcref/anything to the docs
- Version tracking (Translators files and Revision comments)
Work on Emacs and vi sections
Notes need to be added:
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.8 phpdoc/howto/working.xml:1.9
--- phpdoc/howto/working.xml:1.8 Sun Nov 11 04:54:38 2001
+++ phpdoc/howto/working.xml Sun Nov 18 08:05:34 2001
@@ -82,12 +82,12 @@
<listitem><simpara>
Function reference IDs look like this (case should
be consistent with the rest of the function naming
- standards, i.e. lowercase): <literal>function.imageloadfont</literal>.
+ standards, i.e. lowercase): <literal>function.mysql-connect</literal>.
Please note that since underscores cannot be used
in IDs, they should be replaced by minus signs (-).
</simpara></listitem>
<listitem><simpara>
- Function section IDs
+ Function reference section IDs
(<literal><reference id="..."></literal>) look
like this: 'ref.category', for example: 'ref.ftp'.
</simpara></listitem>
@@ -96,17 +96,19 @@
with a role attribute set to "php". Never add any
other programlisting or PHP output with such
a role. It is reserved for PHP source code only.
+ This role is used to detect PHP code and highlight.
</simpara></listitem>
<listitem><simpara>
- The contents of examples with program listings
+ The contents of examples with programlistings
start on column 0 in the XML code.
</simpara></listitem>
<listitem><simpara>
All examples use the <literal><?php ... ?></literal>
- form instead of <literal><? ... ?></literal>. It
- can be useful to use <literal><![CDATA[ ... ]]></literal>
+ form instead of <literal><? ... ?></literal>. Use
+ <literal><![CDATA[ ... ]]></literal>
for examples, since it eliminates the need to change
<literal><</literal> to <literal>&lt;</literal>, etc.
+ Examples look much better, and easily manageable.
</simpara></listitem>
<listitem><simpara>
Indenting, bracketing and naming conventions in
@@ -140,10 +142,9 @@
</simpara></listitem>
<listitem><simpara>
All English XML files should have a <literal><!--
- $Revision --></literal> comment as the first line
- unless they contain an <literal><?xml</literal> tag, in which
- case the revision comment should be on the second
- line. Non-English files should not have this comment.
+ $Revision --></literal> comment as the second line
+ after the <literal><?xml</literal> tag.
+ This comment is not necessary for non-English files.
</simpara></listitem>
<listitem><simpara>
Whitespace changes in the English tree should be
@@ -158,7 +159,7 @@
Never use tabs, not even in example program
listings. XML should be indented with one
space character for each level of indentation;
- example code uses four spaces (see PEAR standards).
+ example code uses four spaces (see PEAR standards).
</simpara></listitem>
<listitem><simpara>
Always use LF (Line Feed) for the only newline
@@ -235,7 +236,8 @@
documented as separate functions. They instead should be
referenced in the parent function as an alias. Functions which
have completely different names, however, should be documented as
- separate entries, for ease of reference. The aliases.xml appendix
+ separate entries, for ease of reference. The
+ <filename>aliases.xml</filename> appendix
is the place to store aliases not documented elsewhere.
</simpara>
@@ -253,10 +255,21 @@
<listitem>
<simpara>
Function names should be created, and documented, in lowercase
- format with an underscore separating the name components. If
- there are several variants, use the one with the least amount
- of components.
- </simpara>
+ format with an underscore separating the name components. Names
+ without underscores are often only kept for backward
+ compatibilty. Document the function named with underscores
+ separating components, and mention the old one as an alias.
+ </simpara>
+ <note>
+ <para>
+ It is up to the PHP developers to give names to functions.
+ A PHP documentation writer only uses the name provided to
+ document the function. If you think that a function name is
+ not appropriate, open a discussion on the
+ <ulink url="&email.phpdev;">&email.phpdev;</ulink> list, by
+ sending a mail to that address.
+ </para>
+ </note>
<simpara>
Good: <literal>mcrypt_enc_self_test</literal>,
<literal>mysql_list_fields</literal>
@@ -284,10 +297,10 @@
</listitem>
<listitem>
<simpara>
- Short code examples are much more desirable than long ones.
- If a function is extremely complex, a suitable place to put
- a longer example is in the chapter introduction. This example
- can hold code for other functions in the same chapter.
+ Short but complete code examples are much more desirable
+ than long ones. If a function is extremely complex, a suitable
+ place to put a longer example is in the chapter introduction.
+ This example can hold code for other functions in the same chapter.
</simpara>
</listitem>
<listitem>
@@ -296,7 +309,10 @@
every function are not appropriate for the reference sections.
Using the errata comments as guidelines, it's easier to tell when
more documentation is needed, as well as the inverse, when too
- much documentation in one section has increased confusion.
+ much documentation in one section has increased confusion.
+ <footnote><simpara>Noone complained about too much documentation
+ in any section till now, so be brave to add longer explanations,
+ and more than one example per function. :)</simpara></footnote>
</simpara>
</listitem>
</orderedlist>
@@ -375,11 +391,12 @@
<example>
<title>Code examples</title>
<programlisting role="php">
-// Use CDATA is you would like to add lots of < to the code
+// Use CDATA here, see the bottom of this page
-// Use a role="php" only for PHP codes. See <computeroutput>,
-// <screen> and other DocBook elements to express other
-// types of listings.
+/* Use a role="php" only for PHP codes. See <screen>
+ * and other DocBook elements to express other
+ * types of listings.
+ */
/* Do all indentation with spaces, not tabs, just to be sure.
* Don't try pushing the code to the right by adding spaces in
@@ -389,7 +406,7 @@
// a function example
function some_code($foo)
{
- /* use four spaces of indentation */
+ // use four spaces of indentation
}
// an example of bracket usage and spacing, always use
@@ -402,7 +419,7 @@
echo "No foo, no bar";
}
-// Include end of CDATA, if you started with CDATA
+// Include end of CDATA, if you started with CDATA, see below
</programlisting>
</example>
@@ -414,7 +431,7 @@
<simpara>
List items must contain a container element such as
simpara or para (there are plenty of others too, see the
- DocBook reference for the listitem element.
+ DocBook reference for the listitem element).
</simpara>
</listitem>
@@ -460,7 +477,8 @@
<para>
For technical reasons, the CDATA start tag: <literal><![CDATA[</literal>
and the CDATA end tag: <literal>]]></literal> is not included
- in the program code above, just the place of them are marked.
+ in the program code above, just the place of them are marked. Use these
+ tags to be able to write clearer example codes.
</para>
</chapter>
@@ -615,6 +633,17 @@
</listitem>
<listitem>
<simpara>
+ Do not translate entity names, such as &true;
+ or &return.success;. These are there to be
+ replaced by their relevant text. Translating them
+ only cause errors. Similarly do not translate any
+ tags (eg. <computeroutput>) to your language.
+ The contents of comments (eg. the bottom of every
+ file) are not to be translated.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
Always make sure, that the modifications you
made to your language's files, are correct.
You may introduce illegal characters. Please
@@ -789,8 +818,17 @@
so the script will only list the files corresponding to
the given maintaner. This HTML files gives you much more
than the <filename>Translators</filename> file. See it
- yourself for example with the Hungarian translation (code:
- hu).
+ yourself for example with the Italian translation (code:
+ it).
+ </para>
+ <para>
+ As this system gets popular in many translation groups,
+ the automatic build process also generates a
+ <filename>revcheck.html</filename> available online
+ in the languages manual directory, as
+ <filename>build.log</filename> is also there.
+ See the Italian translation's file online:
+ <ulink url="&url.revcheck.it;">&url.revcheck.it;</ulink>.
</para>
</sect2>
@@ -813,7 +851,7 @@
<ulink url="&url.status.hu;">&url.status.hu;</ulink>.
</para>
<para>
- This script tries to decide whether a file is up to date or note
+ This script tries to decide whether a file is up to date or not
from the last modification date. The results are not correct if
you modify your languages file, fixing typos, as this script thinks
you modified the file to get in sync with the English one, and will
@@ -886,7 +924,7 @@
this reason the team is thinking about separating the list
to language specific list, so commits in the foreign
languages trees won't posted to the main list. Although
- this is just a plan know.
+ this is just a plan now.
</para>
<para>
If you can't handle the load of this mailing list in
@@ -911,6 +949,16 @@
</simpara>
</listitem>
</itemizedlist>
+ </para>
+ <para>
+ You can also set up some filter on incoming mail messages,
+ so you get the most important things, and can participate
+ in the discussions while do not need to read big diff
+ messages. To ease the filtering the commit messages coming
+ from the CVS server, that are larger then 8kb, are put
+ into attachements. You can always see the commit message
+ and file list in the body, but the diff is in an
+ attachement.
</para>
<para>
There is also a mailing list named <literal>php-notes</literal>.
