Index: working.xml =================================================================== RCS file: /repository/phpdoc/howto/working.xml,v retrieving revision 1.36 diff -u -r1.36 working.xml --- working.xml 23 Jun 2003 09:47:28 -0000 1.36 +++ working.xml 9 Aug 2003 11:49:52 -0000 @@ -409,7 +409,7 @@ Function names should be created, and documented, in lowercase format with an underscore separating the name components. Names without underscores are often only kept for backward - compatibilty. Document the function named with underscores + compatibility. Document the function named with underscores separating components, and mention the old one as an alias. @@ -457,13 +457,13 @@ - Brevity is appreciated. Long winded descriptions of each and + Brevity is appreciated. Long-winded descriptions of each and 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. - Noone complained about too much documentation - in any section till now, so be brave to add longer explanations, + No one complained about too much documentation + in any section until now, so be brave to add longer explanations, and more than one example per function. :) @@ -655,9 +655,9 @@ There are many active translations out there of the PHP - documentation. Some lanaguages are being maintaned by + documentation. Some languages are being maintained by a group of translators (eg. the German), some are one person - projects (eg. the Japanese). There are quite many things for + projects (eg. the Japanese). There are quite a few things for translators to know, though these are simple. @@ -665,7 +665,7 @@ Starting a New Translation Starting a new language translation comes down to - the following simple steps now. + the following simple steps: @@ -678,7 +678,7 @@ Ask for a CVS account. - Mention, that you would like to start a new translation. + Mention that you would like to start a new translation. @@ -696,7 +696,7 @@ and phpdoc-LANGCODE (using the phpdoc-LANGCODE-dir alias) as described in the CVS chapter - of this howto. + of this HOWTO. @@ -716,7 +716,7 @@ revision tracking for help about how can you ease your work of tracking the English - versions, and your languages versions. + version and your language's version. @@ -752,15 +752,15 @@ If you see that a manual for your language is set up, and you would like to join the group, please ask on the appropriate mailing - list about who is responsible to manage that + list about who is responsible for managing that translation. If you are new to the PHP project, and you have no CVS account, you need to request - one account, before you can join the work. Although + an account before you can join the group. Although there are some translations where just a few people have - CVS accounts, and they are responsible for comitting the + CVS accounts, and they are responsible for committing the other's works, this may not be ideal. @@ -788,7 +788,7 @@ Use a system to coordinate with the translators in your language. Currently we have two systems - used paralelly, the Translators files and the + used in parallel, the Translators files and the Revision comments. See the section about revision tracking to learn more about this subject. @@ -833,8 +833,8 @@ made to your language's files, are correct. You may introduce illegal characters. Please always do a make - test before commiting. Introducing an - error in your languages manual can stop the + test before committing. Introducing an + error in your language's manual can stop the automatic updates online until you correct the error. @@ -850,10 +850,10 @@ &url.buildlog.de;. Substitute "de" with your own language code to see the information about your manual. This file - provides you information about the build times, + provides you with 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. + not updated online, it is a good idea to look + into this file and see what the error was. Note, that some browsers like MSIE may @@ -873,7 +873,7 @@ Revision Tracking Working on the translations is not just translating - an English file and commiting the results. Much of + an English file and committing 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 @@ -881,7 +881,7 @@ mailing list, or read the archives. If you never update your files, the translations can get useless. You should also subscribe - to your languages mailing list (if it's not English), + to your language's mailing list (if it's not English), to get CVS commit messages and participate in language specific discussions. @@ -946,7 +946,7 @@ CVS command, or using the web interface at &url.php.cvs;. The web interface can generate really visual diffs, so you can easily spot what needs to be deleted, - added and modified where. + added, or modified, and where. If you choose this method, do not forget to update the revision @@ -969,9 +969,9 @@ 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 + if this is the better method for you or not. Some + languages use the Revision comments and Translators + files in parallel, some use only one of these. It is better to decide, and not to use two systems, as things can get very messy this way. @@ -981,7 +981,7 @@ provide information about. Consider the Translators example above. Now we spread the revision and association - informations in the files mentioned there. Let's see what + information in the files mentioned there. Let's see what would be in the header of the bookinfo.xml file in this case: @@ -989,27 +989,27 @@ - You can see we loose no information here, but we can also + You can see we lose 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. This is extremely - convinient now, as there are more then 4000 files in the + convenient now, as there are more than 4000 files in the English tree. - Currently all the three information is needed. Maintainer - is intended to be a CVS user name, or some nickname without - a space, status can be anything without a space. Note, that - this header is not updated by CVS (in contrast with + Currently, all three fields (English revision, Maintainer, Status) + are needed. Maintainer is intended to be a CVS user name, or some + nickname without a space, status can be anything without a space. + Note, that this header is not updated by CVS (in contrast with $Revision, which is updated automatically). This is only updated when you edit the contents of the comment yourself. 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, but get much more! If + you lose the quick look on the whole list of your + files. No, you do not lose this, but get much more! If you would like to build a list similar to the Translators file given above, you can go to the scripts directory and run: @@ -1021,11 +1021,11 @@ revcheck.html 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, + add a further restriction parameter, the maintainer name, so the script will only list the files corresponding to - the given maintaner. This HTML file gives you much more + the given maintainer. This HTML file gives you much more than the Translators file. See it - yourself for example with the Italian translation (code: + yourself for an example with the Italian translation (code: it). You can also easily run this with make revcheck in the phpdoc root directory, in case you issued a @@ -1096,13 +1096,13 @@ the revcheck.html file. All translators are linked to from the individual files they are assigned to, and there is a nice table showing the state of files for - all the translators. Assingning ready files may be needed if + all the translators. Assigning ready files may be needed if a time consuming update is in progress on that file. - There are two CHM format related things in this XML file. The - first is the <chmindex> part, where you can specify your + There are two CHM format related elements in this XML file. The + first is the <chmindex> element, where you can specify your text to display on the CHM index page, with a link to the actual versions. The editor parameter of a <person> is also used in the grouping of translators on the CHM index page. These @@ -1125,15 +1125,15 @@ Another addon to this system is just to give credit to all people - worked on one file, and not just the current maintainer. To achive + who worked on one file, and not just the current maintainer. To achieve this goal, we added the credit comments. One credit comment in eg. history.xml may look like this (in case - Joe Doe translated the file initally, but Jane followed him to + Joe Doe translated the file initially, but Jane followed him to be the maintainer): <!-- CREDITS: joedoe --> - The credits comment can contain a comma separated list. These + The credits comment can contain a comma-separated list. These comments only affect the display of the translators table in revcheck.html.gz. @@ -1160,7 +1160,7 @@ 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 modify your language's 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 revision @@ -1195,9 +1195,9 @@ LANGCODE is the same language code used in the CVS module name. You can subscribe to / unsubscribe from these mailing lists the same way as above explained, substituting - phpdoc in the email adreesses with your list + phpdoc in the email addresses with your list name. A sample list name is doc-zh for the - Simplified Chineese list. + Simplified Chinese list. Currently these lists (including the main phpdoc list) receive @@ -1220,15 +1220,15 @@ - Other senders: the posting to list is not restricted, + Other senders: posting to the list is not restricted, so people not on the list can also post messages. This - way we got reports and suggestions by plain mails + way we can receive reports and suggestions by plain mail on the list. - The PHP bug tracking system: bug follow ups classified + The PHP bug tracking system: bug follow-ups classified as "Documentation Problem" are posted to the phpdoc list. @@ -1280,9 +1280,9 @@ The commit messages coming from the CVS server, that are larger - then 8kb, are put into attachements. You can always see the + then 8kb, are put into attachments. You can always see the commit message and file list in the body, but the diff is in an - attachement. + attachment. As the Windows HTMLHelp Edition of the manual is evolving