goba Mon Oct 22 08:00:26 2001 EDT
Modified files:
/phpdoc/howto cvs.xml howto.ent howto.xml tools.xml working.xml
Log:
Adding README.translators content, and much, much more :))
Information for translators:
- Starting a new translation (from README.translation)
- Joining an existing translation
- Practical advices for translators (a must read :)
- Revision tracking (Translators, Revision comments, and status.php)
Information about mailing lists:
- Long description and access point listings for phpdoc
- Note about php-notes
Now all README type files except make_chm.README are in the
HOWTO. make_chm.README will be obsolote, as there will come
a new method of generating CHM files (now beta), so I'll not
put the current contents into the HOWTO.
Index: phpdoc/howto/cvs.xml
diff -u phpdoc/howto/cvs.xml:1.1 phpdoc/howto/cvs.xml:1.2
--- phpdoc/howto/cvs.xml:1.1 Sun Oct 21 10:17:00 2001
+++ phpdoc/howto/cvs.xml Mon Oct 22 08:00:26 2001
@@ -29,8 +29,9 @@
changed. The CVS server stores the history of files with
these commit messages. Everybody can then see what was
modified by you, because all modifications generate a diff
- posted to the phpdoc mailing list, and the history is also
- viewable with a CVS client or the web interface at
+ posted to the <link linkend="chapter-maillist">mailing
+ list</link>, and the history is also viewable with a CVS
+ client or the web interface at
<ulink url="&url.php.cvs;">&url.php.cvs;</ulink>. You can
also delete a file or add one with your CVS client,
if you see it is needed.
@@ -408,7 +409,7 @@
</sect1>
<sect1 id="cvs-add">
- <title>Adding files</title>
+ <title>Adding files or directories</title>
<para>
It is sometimes needed to add files to the English files
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.8 phpdoc/howto/howto.ent:1.9
--- phpdoc/howto/howto.ent:1.8 Sun Oct 21 10:17:00 2001
+++ phpdoc/howto/howto.ent Mon Oct 22 08:00:26 2001
@@ -59,6 +59,19 @@
<!ENTITY url.xsl.xep "http://www.renderx.com/";>
<!ENTITY url.sunjava "http://java.sun.com/";>
+<!-- For Working section -->
+<!ENTITY url.langcodes "http://www.unicode.org/unicode/onlinedat/languages.html";>
+<!ENTITY url.buildlog.de "http://www.php.net/manual/de/build.log";>
+<!ENTITY url.listarchive "http://marc.theaimsgroup.com/?l=phpdoc";>
+<!ENTITY url.listnews "news://news.php.net/php.doc";>
+<!ENTITY url.listnewshttp "http://news.php.net/group.php?group=php.doc";>
+<!ENTITY url.docsubscribe "[EMAIL PROTECTED]">
+<!ENTITY url.docunsubscribe "[EMAIL PROTECTED]">
+<!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";>
+
+
<!-- For Misc section -->
<!ENTITY url.zend.phpfunc "http://www.zend.com/phpfunc/";>
Index: phpdoc/howto/howto.xml
diff -u phpdoc/howto/howto.xml:1.14 phpdoc/howto/howto.xml:1.15
--- phpdoc/howto/howto.xml:1.14 Sun Oct 21 10:17:00 2001
+++ phpdoc/howto/howto.xml Mon Oct 22 08:00:26 2001
@@ -19,7 +19,6 @@
<!-- TODO
Files to incorporate:
- README.translations
make_chm.README
Sections need to be added:
Index: phpdoc/howto/tools.xml
diff -u phpdoc/howto/tools.xml:1.1 phpdoc/howto/tools.xml:1.2
--- phpdoc/howto/tools.xml:1.1 Sun Oct 21 10:17:00 2001
+++ phpdoc/howto/tools.xml Mon Oct 22 08:00:26 2001
@@ -221,8 +221,9 @@
editors, such as XML Spy, because the often friendly auto-indent,
and optimize features can make the XML files so different from
the one you started the work with, that the diff posted to our
- mailing list and used by translators will be useless. Emacs
- is also available for Windows if you would like to give it a try ;)
+ <link linkend="chapter-maillist">mailing list</link> and used
+ by translators will be useless. Emacs is also available for
+ Windows if you would like to give it a try ;)
</para>
<para>
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.1 phpdoc/howto/working.xml:1.2
--- phpdoc/howto/working.xml:1.1 Sun Oct 21 10:17:00 2001
+++ phpdoc/howto/working.xml Mon Oct 22 08:00:26 2001
@@ -454,6 +454,464 @@
</para>
</chapter>
+ <chapter id="chapter-translation">
+ <title>Information for Translators</title>
+
+ <para>
+ There are many active translations out there of the PHP
+ documentation. Some lanaguages are being maintaned by
+ a group of translators (eg. the German), some are one person
+ projects (eg. the Japanese). There are quite many things for
+ translators two know, though these are simple.
+ </para>
+
+ <sect1 id="translation-starting">
+ <title>Staring a New Translation</title>
+ <para>
+ Starting a new language translation comes down to
+ the following simple steps now.
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Consult the <link linkend="chapter-maillist">mailing
+ list</link> to see if the translation is already in progress.
+ If it is, disregard the following and coordinate with the
+ other translators on the list.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <link linkend="cvs-account">Ask for a CVS account</link>.
+ Mention, that you would like to start a new translation.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Create a sudirectory with the appropriate language
+ code, or ask for help about how you can do this on the
+ list. Appropriate languages codes can be found at
+ <ulink url="&url.langcodes;">&url.langcodes;</ulink>.
+ See the CVS chapter about <link linkend="cvs-add">how
+ to add a file or directory</link>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Copy <filename>en/language-defs.ent</filename> and
+ <filename>en/language-snippets.ent</filename> to the
+ new directory and translate the contents of them.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Copy over files from the English tree and start to
+ work on them, (do not check in untranslated files)
+ and rerun configure each time you add a file.
+ See the section about
+ <link linkend="translation-revtrack">revision
+ tracking</link> for help about
+ how can you ease your work of tracking the English
+ versions, and your languages versions.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Some important issues to consider when building
+ a new translation:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Can you set up and translate the whol manual
+ yourself? If not, can you set up a team to
+ work on the language?
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Have you made sure that your language or glyph
+ (lettering, font, or characters) is supported
+ by the DocBook stylesheets? Please ask on the
+ <link linkend="chapter-maillist">mailing list</link>
+ if you don't know.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1 id="translation-joining">
+ <title>Joining To a Translation</title>
+ <para>
+ If you see that a manual for your language is set
+ up, and you would like to join the group, please
+ ask on the <link linkend="chapter-maillist">mailing
+ list</link> about who is reponsible to manage that
+ translation.
+ </para>
+ <para>
+ If you are new to the PHP project, and you have no
+ CVS account, you need to <link linkend="cvs-account">request
+ one account</link>, before you can join the work. Although
+ there are some translations where just a few people have
+ CVS accounts, and they are responsible for comitting the
+ other's works, this may not be ideal.
+ </para>
+ </sect1>
+
+ <sect1 id="translation-practical">
+ <title>Practical Advices for Translators</title>
+ <para>
+ Here are some some advices we collected for translators:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Only commit translated files in your language's directory.
+ The build process is responsible for adding English
+ files in place of the files you have not committed.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Use a system to coordinate with the translators
+ in your language. Currently we have two systems
+ used paralelly, the Translators files and the
+ Revision comments. See the section about
+ <link linkend="translation-revtrack">revision
+ tracking</link> to learn more about this subject.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ While translating, you will find errors in the
+ English manual. If you are sure about an error,
+ that should be corrected, please correct the
+ found errors yourself. If you are not sure,
+ whether you found an error or not, please ask
+ on the <link linkend="chapter-maillist">mailing
+ list</link>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ We have the global entities used all over
+ the manuals in <filename>global.ent</filename>.
+ If you would like to define entities only used
+ in your language, an ideal place for these
+ is <filename>your_language/language-defs.ent</filename>.
+ See <filename>hu/language-defs.ent</filename> for
+ an example.
+ </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
+ always do a <link linkend="chapter-validating">make
+ test</link> before commiting. Introducing an
+ error in your languages manual can stop the
+ automatic updates online until you correct the
+ error.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ If your manual is online at the PHP mirror
+ sites, you can check out the building log
+ of the several downloadable formats and
+ online manuals by downloading the
+ <filename>build.log</filename> file of your
+ language. For the German translation, this file is:
+ <ulink url="&url.buildlog.de;">&url.buildlog.de;</ulink>.
+ Substitute "de" with your own language code to
+ see the information about your manual. This file
+ provides you information about the build times,
+ and errors (if there were any). If the manual is
+ not updated online, it is a good idea, to look
+ into this file and see what was the error.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1 id="translation-revtrack">
+ <title>Revision Tracking</title>
+ <para>
+ Working on the translations is not just translating
+ an English file and commiting the results. Much of
+ the work is needed to update the already translated
+ ones, to get in sync with the content of the English
+ files. To follow the modifications in the English
+ tree, you should subscribe to the
+ <link linkend="chapter-maillist">mailing list</link>,
+ or read the archives. If you never update your files,
+ the translations can get useless.
+ </para>
+ <para>
+ Updating a foreign language file can get difficult,
+ as you may not know when and who translated that file,
+ so you may not know where you should look for the
+ updates needed. We have two (plus one) system for tracking
+ the revisions and modification dates of the files in
+ <literal>phpdoc</literal>.
+ </para>
+
+ <sect2 id="translation-revcheck-translators">
+ <title>The Translators Files</title>
+
+ <para>
+ Nearly all translations are currently using a
+ <filename>Translators</filename> file just in the
+ root of their translation's tree. This file
+ can contain the names, email addresses, and CVS
+ user names of the contributors of this translation,
+ and the list of files translated.
+ </para>
+
+ <para>
+ Along with the XML file names, associations between
+ translators and files, revision numbers, and status
+ information can also be stored. One sample Translators
+ file, for the imaginary xx language can look like this:
+ <programlisting>
+=============================================================================
+CVS User Name Contact email address
+=============================================================================
+joedoe Joe Doe [EMAIL PROTECTED]
+jane Jane Smith [EMAIL PROTECTED]
+...
+
+=============================================================================
+Filename Translator Revision
+=============================================================================
+bookinfo.xml jane 1.16
+language-defs.ent jane 1.7
+language-snippets.ent joedoe 1.8
+preface.xml
+------- appendices ----------------------------------------------------------
+aliases.xml joedoe working
+debugger.xml
+escaping.xml
+history.xml jane 1.2
+...
+ </programlisting>
+ In this example you can see the listing of translators, and
+ the first few lines of the list of files. Here you can store
+ the assignment of the file, the revision number (what English
+ file this translation was based on), and if there is no revision
+ number yet, a status (eg. working).
+ </para>
+ <para>
+ When it is time to update a file (eg. bookinfo.xml jumped to
+ 1.20 as time passed), you can ask for a diff between 1.16 and
+ 1.20, and you'll see what modifications you need to port to
+ the translated file. You can ask for diffs by using the diff
+ CVS command, or using the web interface at <ulink url="&url.php.cvs;">
+ &url.php.cvs;</ulink>. The web interface can generate really
+ visual diffs, so you can esaily spot what needs to be deleted,
+ added and modified where.
+ </para>
+ <para>
+ If you choose this method, do not forget to update the revision
+ numbers stored in the <filename>Translators</filename> as
+ you update files in your language's tree.
+ </para>
+ </sect2>
+
+ <sect2 id="translation-revcheck-comments">
+ <title>The Revision Comments</title>
+
+ <para>
+ There is another way of tracking versions instead of
+ using the method descibed above. You can decide yourself,
+ as this is the better method for you or not. Some
+ languages use the Revision comments and Translators files
+ paralelly, some use only one of these. It is better to
+ decide, and not to use two systems, as things can get
+ messy this way.
+ </para>
+ <para>
+ Instead of storing all responsibilities in a central file,
+ the revision comment system stores them in the files they
+ provide information about. Consider the <link
+ linkend="translation-revcheck-translators">Translators</link>
+ example above. Now we spread the revision and association
+ informations in the files mentioned there. Let's see what
+ would be in the header of the <filename>bookinfo.xml</filename>
+ file in this case:
+ <programlisting>
+<!-- EN-Revision: 1.16 Maintainer: jane Status: ready -->
+ </programlisting>
+ </para>
+ <para>
+ You can see we loose no information here, but we can also
+ add some other status information in the case it is needed
+ (eg. "partial" for incomplete translations). This revision
+ comment system is basically about storing the information in
+ the XML files, and not in a central place.
+ </para>
+ <para>
+ Currently all the three information is needed. Maintainer
+ is intended to be a CVS user name, status can be anything
+ without a space. Note, that this header is not updated
+ by CVS (as <literal>$Revision</literal> is updated
+ automatically). This is only updated when you edit the
+ contents of the comment.
+ </para>
+ <para>
+ You may see this as a good thing, but using these comments,
+ you loose the quick look on the whole list of your
+ files. No, you do not loose this, and get much more! If
+ you would like to build a list similar to the
+ <filename>Translators</filename> file given above, you
+ can go to the scripts subdirectory of phpdoc, and run:
+ <programlisting>
+./revcheck.php xx
+ </programlisting>
+ Here <literal>xx</literal> is the imaginary language code.
+ After running this script you'll get a
+ <filename>revcheck.html</filename> in the same directory.
+ You can find revision comparisions and links to diffs
+ for all the files in this language. You can also
+ add a furter restriction parameter, the maintainer name,
+ 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).
+ </para>
+ </sect2>
+
+ <sect2 id="translation-revcheck-status">
+ <title>The Online Status Script</title>
+
+ <para>
+ Rasmus Lerdorf developed on online status checking script.
+ This script is most useful for files without revision comments,
+ so if you use the Revision comments, use the specific script
+ <link linkend="translation-revcheck-comments">mentioned above</link>.
+ </para>
+ <para>
+ You can access the script at: <ulink url="&url.status;">&url.status;</ulink>.
+ Visiting this page, you need to wait for some time to generate,
+ as it builds a whole table of file and dates information about
+ all translations. If you would like to restrict the table to only
+ one translation, you can provide the <literal>?l=langcode</literal>
+ URL parameter, so to view the Hungarian status, visit:
+ <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
+ 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
+ mark your file as up to date. Although this script can help some
+ to track files without <link linkend="translation-revcheck-comments">revision
+ comments</link>, if you use revision comments, you can get more
+ accurate results than this script, and much more than that.
+ </para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter id="chapter-maillist">
+ <title>The phpdoc and php-notes Mailing Lists</title>
+
+ <para>
+ The XML content of <literal>phpdoc</literal> files is
+ updated from day to day, and on busy days from hour to
+ hour. To follow the updates in the English tree and
+ any other language's tree and also participate in
+ the discussions, it is highly recommended that you
+ subscribe to the <email>&email.phpdoc;</email> mailing
+ list. You can subscribe by sending a blank mail to
+ <ulink url="&url.docsubscribe;">&url.docsubscribe;</ulink>.
+ Similarly you can unsubscribe by sending a blank mail to
+ <ulink url="&url.docunsubscribe;">&url.docunsubscribe;</ulink>.
+ There is a web interface for these tasks at <ulink
+ url="&url.support;">&url.support;</ulink>.
+ </para>
+ <para>
+ Currently this list receives messages from the following senders:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Members of the list: discussion threads about anything
+ related to the phpdoc team.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ The CVS server: diffs about every small modification
+ in the English or any languages XML files, or other
+ support files placed in the <literal>phpdoc</literal>
+ repository.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ The PHP bug tracking system: bug follow ups classified
+ as "Documentation Problem" in the bug system.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Other senders: the posting to list is not restricted,
+ so people not on the list can also post messages. This
+ way we got bug reports and suggestions by plain mails
+ on the list.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ SPAM: this is not a common piece of mail, thanks to
+ or SPAM protection system.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ This long list of mail types can be scaring for someone,
+ who can't process the many mails posted to the list. For
+ 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.
+ </para>
+ <para>
+ If you can't handle the load of this mailing list in
+ your mailbox, you can read the messages three ways:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ On the web, in the archives at
+ <ulink url="&url.listarchive;">&url.listarchive;</ulink>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ With a news reader at
+ <ulink url="&url.listnews;">&url.listnews;</ulink>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ On the web, with the experimental news interface at
+ <ulink url="&url.listnewshttp;">&url.listnewshttp;</ulink>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ There is also a mailing list names <literal>php-notes</literal>.
+ You can access it the same way as the <literal>phpdoc</literal>
+ list (just substitute <literal>phpdoc</literal> with
+ <literal>php-notes</literal>). This list is the place where
+ all the manual notes are posted. You may consider subscribing
+ to this mailing list if you would like to help manage the notes.
+ </para>
+ </chapter>
+
<chapter id="chapter-misc">
<title>Miscellaneous Notes</title>
@@ -462,85 +920,6 @@
http://www.zend.com/phpfunc/, etc.
</para>
</chapter>
-
- <!--
-
- ! These paras are from the howto.xml made by Stig (this
- ! is actually HTML). Can be useful to make the new XML
- ! file section.
-
- <a name="connecting.phpdoc"></a><h2>3.1. New SGML files</h2>
-
- The main file for the documentation is <tt>manual.sgml</tt>. This
- file uses <i>entities</i> (can be compared to a combination of #define
- and #include in C) to include text from other files. The entities
- that include the PHPDOC files are defined in the <i>preamble</i> of
- <tt>manual.sgml</tt>, which is the section between the "[" character
- on the first (DOCTYPE) line and "]>".
-
- <p> Steps involved in connecting a new PHPDOC file:
-
- <ol>
- <li> Let us say you have written functions/ldap.phpdoc. You should
- then add this to the preamble:
- <pre>
- <b><!entity ldapref system "functions/ldap.sgml"></b>
- </pre>
-
- This tells the SGML parser that when "ldapref" is referenced it
- should read the file <tt>functions/ldap.sgml</tt>.<p> <em>Note
- that the file name extension used here is not <tt>.phpdoc</tt>,
- but <tt>.sgml</tt>. The Makefile handles the conversion.</em>
- <p>
-
- <li> Refer to the <i>ldapref</i> entity where you want to include it.
- Keep in mind that PHPDOC documents are converted into LINUXDOC
- sections. Internal functions should be added to the "internal
- functions" chapter in <tt>chapters/functions.sgml</tt>. Add
- something like this (the bold part is what to add):
- <pre>
- <chapt>Internal functions
- ...
- <b>&ldapref;</b>
- ...
- </pre>
-
- <li> Then, to make sure the .phpdoc file is converted to .sgml,
- you have to tell make about it. Add the <u>.sgml</u> file to
- the FUNCREF variable in <tt>Makefile.in</tt>. Example (the bold
- text is the change):
- <pre>
- FUNCREF=functions/oracle.sgml \
- <b>functions/ldap.sgml \</b>
- functions/math.sgml \
- functions/mysql.sgml \
- functions/pgsql.sgml \
- functions/strings.sgml \
- functions/adabas.sgml
- </pre>
-
- <li> Finally, regenerate <tt>Makefile</tt>:
- <pre>
- (cd .. ; ./config.status)
- </pre>
-
- </ol>
-
- <a name="connecting.labels"></a><h2>3.2. Label name conventions</h2>
-
- When making or refering to labels in the LINUXDOC files, there are
- some conventions that should kept:
-
- <ul>
- <li> Internal functions have labels of the form
- <tt>func:<i>function_name</i></tt>.
- <li> Arguments to configure (when installing) have labels like the
- argument names. For example, the -with-system-regex option has
- the label <tt>with_system_regex</tt>
- </ul>
- <hr>
-
- -->
<!-- Keep this comment at the end of the file
Local variables:
